genderapi_error: GenderAPI error conditions

In genderapi: Official 'GenderAPI.io' V2 Client

GenderAPI error conditions

Description

All errors raised by this package inherit from genderapi_error, so they can be caught with tryCatch(..., genderapi_error = function(e) ...). More specific classes:

Details

• genderapi_validation_error: the input failed a client-side check. No request was sent and nothing was billed.

• genderapi_http_error: the API answered with HTTP 400 or higher. Fields: status, code, title, detail, action, errors (validation pointers), documentation, request_id (from the body, meta$request_id or the X-Request-ID header), retry_after (the Retry-After header as a string), billing_status, usage (meta$usage), meta, data (the item array of an all-failed batch), body (parsed JSON or NULL), raw (the response text) and headers.

• genderapi_redirect_error: the API answered with a 3xx redirect. It was not followed, so the key was not forwarded. Fields: status, location, headers.

• genderapi_transport_error: no usable response (network error or timeout). code is "timeout" or "transport_error". The request may still have been processed and billed.

• genderapi_response_error: a 2xx response that is not a JSON object. code is "invalid_response".

• genderapi_access_mode_error: an API key is set but a successful response reports an access mode other than "api_key" in meta$access$mode (usually "ip_trial", because the key was not recognized). code is "unexpected_access_mode". The request has already been processed and may have consumed IP-trial credits; it is not retried. Fields: access_mode, access_reason, result (the complete parsed result the function would have returned, including meta$usage), status and request_id. Disable the check with genderapi_client(require_api_key_access = FALSE).

The package never retries. After a 429 wait for retry_after seconds; the next request is a new, billable operation. When billing_status is "unconfirmed" or action is "contact_support", contact support with request_id before sending the request again. Match on code, never on the human-readable detail. See genderapi_error_catalog().

Error bodies can contain the submitted input. Do not log them wholesale.

Examples

client <- genderapi_client(api_key = NULL)
e <- tryCatch(genderapi_name("", client = client), genderapi_error = function(e) e)
class(e)
conditionMessage(e)

genderapi documentation built on Oct. 1, 2026, 5:13 p.m.