Skip to content

Guides

Errors

The API answers with an ordinary HTTP status. An error also has a body with a fixed code your system can act on and a message for a person.

Statuses

Errors are returned as JSON with code and message. At 422 the answer also has errors with one field per error.

StatusWhat it means
400Invalid request.
401The key is missing, deleted or expired.
403The key does not have the scope, the organisation has no access to the unit, or the subscription is not active.
404Not found.
409The request cannot be carried out as things stand, for example because the component is already replaced.
422Validation failed. The answer has errors with one field per error.
429The request limit is reached. Wait the number of seconds given in Retry-After.

The error model

  • code string required

    A fixed code, such as unauthenticated, missing_scope, forbidden, subscription_inactive, blocked, not_found, conflict, validation_failed or rate_limited.

  • message string required

    An explanation for a person.

  • errors object

    Only at 422. One field per error, each with a list of messages.

Response 403 
{
  "code": "missing_scope",
  "message": "The key does not have the scope units:write."
}
Response 422 
{
  "code": "validation_failed",
  "message": "The name field is required.",
  "errors": {
    "name": [
      "The name field is required."
    ]
  }
}

Handling errors

  • Act on code, which does not change. message is for a person and may be reworded.
  • At 429, wait the seconds in Retry-After and try again.
  • At 5xx or a network error, try again with a growing pause. Send Idempotency-Key with a POST, so a retry never makes two records.
  • At 401, the key is missing, deleted or expired: make a new one in the app.
Esc