Envelope
Successful responses return{ "data": … }. Failures return an error object
and a non-2xx HTTP status. Branch on the status code, not a body flag:
Responses from data endpoints also carry an
X-Request-Id header; include it
when reporting an issue.
Types and codes
Not every endpoint emits every code; each endpoint’s reference page lists its
own. A “no match” is never a
404; it’s a successful 200: single-record
lookups return found: false, and searches return an empty list. A 404
means the endpoint or job id itself doesn’t exist.Async lookups can fail as a job rather than an HTTP error. A
failed job carries the same
error object in the envelope. When the source
was down or not answering, it is type: "upstream_error" with the source’s
<source>_upstream code and a message saying when to retry; retry the job
later. Any other failure is code: "job_failed".