minimusdocs
Help center

Errors

What each answer code means, what the body says, and what to do about it.

A call that worked answers 200 (here it is), 201 (made), 202 (started in the background) or 204 (done, nothing to show). Anything else is one of these:

Code Means What to do
400 Something you sent is not valid. Read the body: it names each field that is wrong. Fix and send again.
401 No key, or a key that is wrong, expired or revoked. Check the Authorization header. Make a new key if this one was revoked.
403 The account may not do this, or the key's or app's scopes do not allow it. Check the account's permissions in the dashboard, and the scope the call needs.
404 Nothing with this id, or nothing the account can see. Also a path without its final /. Check the id, and that the account can see it in the dashboard.
405 This path does not take this method. Check the method in the API reference.
409 It clashes with the current state, or an Idempotency-Key was reused for another request. Read the body; for a key, make a new one for the new request.
413 What you sent is too large. Send a smaller file, or fewer items at once.
429 Too many requests. Wait the seconds in the Retry-After header, then try again. See Rate limits.
500, 502, 503 Something failed on the panel's side. Try again in a moment. If it keeps happening, tell your panel's operator, with the time of the call.

What the body says

Most errors answer a detail in plain words:

{ "detail": "You do not have permission to perform this action." }

A 400 names each field that is wrong, with what is wrong with it:

{
  "username": ["A line with that username already exists."],
  "max_connections": ["Ensure this value is less than or equal to 10."]
}

Problems that are not about one field come under non_field_errors or detail.

When the key itself is refused

A refused key answers a detail in plain words and a code your integration can act on:

{ "detail": "This key cannot make changes. It needs \"Change\": make a new key with it ticked.", "code": "scope_write" }
Code Answer Means
key_invalid 401 No key with that secret. Check you copied all of it.
key_revoked 401 The key was revoked. Make a new one.
key_expired 401 The key ended. Make a new one.
account_refused 401 The key's account is turned off, or cannot use the API (single sign-on).
address_refused 403 The key only works from its listed addresses, and this is not one.
scope_read, scope_write, scope_manage 403 The key lacks the scope this call needs.
session_only 403 No key or AI app can make this call: it is the dashboard's only.

A 403 without a code comes from the account's own permissions: the account could not do this in the dashboard either.

Retrying

  • 400, 403, 404, 405: retrying the same request gets the same answer. Change something first.
  • 409 for an Idempotency-Key: make a new key.
  • 429 and 5xx: retry later, waiting a little longer each time (1 s, 2 s, 4 s…). For calls that spend credits, retry with the same Idempotency-Key so nothing happens twice.