Errors

Every error response — any status other than 200/202 — carries one JSON shape, wrapped under error:

{
  "error": {
    "code": "not-found",
    "message": "no creator found for instagram/somehandle",
    "details": { "reason": "account-not-discoverable", "retryable": true }
  }
}

Field	Contract
error.code	Stable and machine-readable. Branch on this. Maps 1:1 to the HTTP status.
error.message	Human prose for logs and error screens. Never parse it — wording can change any time.
error.details	Optional structured extras. Today’s one use: a read-miss 404 carries error.details.reason.
error.details.retryable	Only present on error.details, and only true — never false or explicitly absent-as-false. Present and true means the miss was on our side, not a fact about the entity: retry after a few minutes. Absent means terminal: stop retrying.

The codes

code	HTTP	When
unauthorized	401	Missing, malformed, expired, or revoked credential.
forbidden	403	Valid credential, but it lacks the <resource>:<action> permission this endpoint requires.
not-found	404	Single reads: a read miss (check error.details.reason — retry only if error.details.retryable is true), an unknown asProfile, or an unsupported network.
invalid-input	400	A malformed request — e.g. a batch over the 100-identifier cap, or an unparseable identifier.
rate-limited	429	Request budget exceeded. Carries a Retry-After header — see rate limits.
internal-error	500	Server-side fault. The message is deliberately generic; internal error detail is never exposed. Safe to retry with backoff.
unavailable	503	A dependency required to verify the credential is unreachable; the credential was neither accepted nor rejected. Safe to retry with backoff.

Evolution across this whole API is additive-only: a response may gain a new field, and any open vocabulary (like the code set above) may gain a new value, at any time. Never reject an unknown field or an unrecognized value you don’t branch on — implement a default case instead.

A 202 fetching response and a batch item landing in fetching or unavailable are not errors — these are ordinary read outcomes with their own contract.

Contacting support

Include the x-request-id response header of the failing call. It is present on every response and identifies the specific request.