Skip to main content

Format

Every error returns JSON with a readable detail:
When the client needs to react to a specific case, the body also carries error: a stable code that does not change even if the text does. Code against error, not against detail.
Error messages (detail) are in Spanish. Stable codes (error) and field names are the same in every language.
Parameter validation errors (422) use the standard format: detail is a list with each field and its problem.

Status codes

No error uses credits.

Most common stable codes

There are others, specific to each endpoint family and documented in the reference. For example, ai_disabled (403) when your organization turned off AI or web search, and the audit codes: bad_id, audit_id_mismatch, not_found, unknown_section and audit_source_unavailable.

Source failure or empty result

Every read from a data source ends in one of three ways: data, an empty result the source asserted, or a failure. A failure is never presented as «no data».
If the address or transaction you asked for could not be read, the response is 503 with a structured reason and no charge:
When retry_after is present, the response also carries the Retry-After header.
No failure is cached: the next query asks the source again.

Reasons (reason)

source_fault says whether it was a failure of the source (true) or a cap or a query that was not made (false), and failure_cause explains why, in one sentence.
To find out whether a source is down and until when, query GET /v1/sources (free).