SignalHandle errors deliberately
Use HTTP status, machine-readable error codes, and request IDs to recover safely without repeating successful paid work.
Top-level error response
Most failed requests return an error object. Include the X-Request-Id response header or error.request_id when reporting a problem, without sending API keys. Batch item failures use their own error objects; inspect each item.
{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "No credits remaining. Cached and sample results remain free.",
"request_id": "example-request-id"
}
}400: request validation
INVALID_PLATFORM, INVALID_HANDLE, INVALID_MODE, INVALID_FRESHNESS, and INVALID_BATCH identify invalid lookup input. INVALID_JSON identifies malformed JSON when generated by the application error handler; framework parser errors can use their own code. INVALID_NAME and KEY_LIMIT relate to key creation. Correct the input before retrying.
401 and 403: access
UNAUTHENTICATED means missing, invalid, expired, or revoked credentials; INVALID_LOGIN means the email/password combination failed. INVALID_ORIGIN rejects a browser mutation from a different origin. Repeating the same request without fixing credentials or origin will not help.
402, 404, 409, and 422
INSUFFICIENT_CREDITS prevents a fresh request when the balance is exhausted. PROFILE_NOT_FOUND indicates an unavailable upstream profile where reported as 404; NOT_FOUND identifies an unknown resource. RESULT_EXPIRED means a saved lookup must be refreshed. PROFILE_UNAVAILABLE covers inaccessible/private profiles or a provider’s unavailable response; it should not be treated as permission to access private data.
429: slow down
RATE_LIMITED returns Retry-After: 60. Wait at least that long and use backoff with jitter; login or signup protections can have longer windows, so repeated retries can remain blocked. The beta caps authenticated HTTP requests at 120/minute per account, and API requests at 300/minute per IP, with additional login/signup limits. These process-local safeguards are not a guaranteed sustained throughput allocation.
502 and 503: provider or service issue
UPSTREAM_UNAVAILABLE, UPSTREAM_ERROR, and UPSTREAM_INVALID identify provider transport, response, or schema failures. Public pages can be blocked or require login; unsupported live platforms and LOOKUP_BUSY can return service-unavailable errors. Do not retry an unsupported platform indefinitely. For transient failures use bounded backoff; failures do not consume customer credits. A successful provider call can still have occurred after a transport disconnect, so review usage before forcing another live fetch.
500: unexpected failure
Stop tight retry loops, retain the request ID, and contact the operator. Never log full authorization headers or credentials. POST lookup requests do not support a client idempotency key: do not promise exactly-once upstream execution across transport failures.