Which errors should my client retry?

Retry 429 after Retry-After seconds, and 500 or 504 with a backoff of a few seconds. Do not retry 401, 402, 404 or 405: the same call fails again.

Why do I get 405 for a TMDB endpoint?

amodb does not offer TMDB account, session, rating and list write methods. They return 405 with status_code 37. Read endpoints all work.

amodb errors: TMDB status codes and OMDb error responses

Errors

TMDB style calls return errors in the TMDB body: success false, a numeric status_code and a status_message. OMDb style calls return Response False with an Error string. amodb uses 8 TMDB codes, from 7 for an invalid key to 25 for the rate limit and 36 for an expired plan. Retry only 429, 500 and 504.

TMDB style error body

Every error from https://api.amodb.dev/3 has the same JSON shape as TMDB:

JSON

{
  "success": false,
  "status_code": 34,
  "status_message": "The resource you requested could not be found."
}

Error codes

HTTP	status_code	status_message	What to do
401	7	Invalid API key: You must be granted a valid key.	Check the key and how you send it.
401	10	Suspended API key: Access to your account has been suspended, contact amodb.	Write to support@amodb.dev.
402	36	Your plan has expired. Renew at https://amodb.dev/pricing	Pay for a new period.
404	34	The resource you requested could not be found.	Check the id or path.
405	37	This method is not offered by amodb.	Use a read endpoint.
429	25	Your request count (N) is over the allowed limit of (L).	Wait for `Retry-After` seconds.
500	11	Internal error: Something went wrong, contact amodb.	Retry after a few seconds.
504	24	Your request to the backend server timed out. Try again.	Retry after a few seconds.

OMDb style error body

The OMDb compatible endpoint keeps the OMDb shape and wording:

An OMDb call with r=xml returns HTTP 400. Use r=json or leave r out.

JSON

{
  "Response": "False",
  "Error": "Movie not found!"
}

Handle errors in code

JavaScript Python

const res = await fetch("https://api.amodb.dev/3/movie/550", {
  headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` },
});
if (!res.ok) {
  const err = await res.json();
  if (res.status === 429) {
    // wait Retry-After seconds, then retry
  }
  throw new Error(`amodb ${res.status} code ${err.status_code}: ${err.status_message}`);
}

res = requests.get(url, headers=headers, timeout=10)
if not res.ok:
    err = res.json()
    raise RuntimeError(f"amodb {res.status_code} code {err['status_code']}: {err['status_message']}")

Fallbacks that are not errors

An unknown language tag does not fail. amodb serves English for it.
A field with no data is null or an empty array, as in TMDB.