The basics — IV

Errors

Errors come back as JSON with a single error key and an HTTP status that matches. There is no error code enum and no request id.

Every error looks like this

{
  "error": "Forbidden - Invalid API Key"
}

Statuses

What each status means
Status	Meaning	Retry?
200	Success. The body is the data itself, not wrapped in an envelope.	—
403	The key is missing, unknown or revoked. The response does not distinguish between them.	No — fix the key
404	The route was valid but nothing matched. Also returned for a path the API does not recognise at all.	No
429	Too many requests on this key. Wait for the number of seconds in the `Retry-After` header.	Yes, after Retry-After
500	The archive could not be read. Transient.	Yes, with backoff

404 is normal

A search that matches nothing is a 404, not a 200 with an empty array. If you are looking a name up on behalf of a user, expect 404 as an ordinary outcome rather than a failure, and check the spelling before assuming the data is missing.

Most common cause

A 404 from the person or film endpoints almost always means the name did not match exactly. These endpoints do not do fuzzy matching, case folding or partial matches. “michael b. jordan” will not find “Michael B. Jordan”.

Unknown routes

A path that matches no endpoint returns 404 with a pointer back to this site, so a typo in your URL is distinguishable from an empty result by its body.

404 on an unknown path

{
  "error": "Not Found",
  "documentation": "https://developer.uractor.com/"
}

Retrying

Retry 500s with exponential backoff and a cap. Retry a 429after the number of seconds given in its Retry-After header. Do not retry 403 or 404 — nothing about the response will change on a second attempt. See limits and fair use for the rate limit itself.