Skip to main content

Errors format

Error conventions#

Backend errors follow these two conventions:

  • Always return the HTTP error code that fits the situation.
  • Return a JSON object of this shape:
{
"code": "{Code}",
"desc": "free format description",
"origin": "{Origin}",
"details": {
"{DetailKey}": "{DetailValue}",
"{DetailKey}": "{DetailValue}",
},
}

All terms inside brackets are described in the following sections...

Code#

The code is a string used internally and by consumer for better error identifications & reactions.

It is defined by an exhaustive list of values. Most of codes correspond to HTTP statuses found in the Mozilla documentation.

We use this link as general specifications for errors and not just for http request errors.

Classic codes: codes corresponding to http status codes

  • bad_request: 400, bad request - wrong request format.
  • unauthorized: 401, a required valid token is missing/malformed/expired.
  • forbidden: 403, accesses checks failed - action impossible.
  • not_found: 404, the resource/route has been not found.
  • method_not_allowed: 405, the HTTP verb is not supported for the requested route.
  • conflict: 409, the action cannot be performed considering the current state of the server.
  • unprocessable_entity: 422, the received entity is not processable.
  • internal: 500, something internal to the service has failed.
  • ...

Redirect codes: code encountered in query parameter error_code on redirections

  • invalid_flow: the authorization server has raised en error, please check the description to know more about it.
  • login_required: while an auth flow was initiated with prompt=none parameter but could not be respected because of authentication is required.
  • consent_required: while an auth flow was initiated with prompt=none parameter but could not be respected because of consent is required.
  • missing_parameter: a required parameter is missing from the request.
  • internal
  • ...

Special codes: special codes that should not be encountered externally ⚠️ Please contact the backend team if you receive one these codes.

  • unknown_code: 500, something internal to the service has failed.
  • no_code: xxx, no specific code defined.

Origin#

Origin is an information about where the error does come from.

Possible origins:

  • body: body parameter.
  • query: query parameters.
  • path: path parameters.
  • headers: headers.
  • internal: internal logic.
  • ...

Special origins: special origins that should not be encountered externally ⚠️ Please contact the backend team if you receive one of these origins.

  • not_defined: the error has no origin defined yet

Details#

An object containing a dynamical number of detail objects.

Each detail object is built with a DetailKey and a DetailValue:

-> A DetailKey is a dynamical string representing a field name, a parameter value, a resource id...

-> A DetailValue describes an error code as a string for clearer consumer error identification & reactions. It represents codes related to a detail key.

Possible detail values:

  • conflict: unique, conflict with a state machine logic...
  • malformed: email format, ip address format...
  • invalid: minumum/maximum value/lenght...
  • required: missing in request...
  • expired: expired duration...
  • forbidden: forbidden to update...
  • internal: internal error occured
  • locked: cannot be updated
  • not_found: correspondance has not been found
  • not_supported: not handled by the running implementation
  • timed_out: something... timed out
  • unauthorized: authorization is missing

Special detail values: ⚠️ Please contact the backend team if you receive one of these detail values.

  • unknown: unknown detail code
  • no_code: no specific code

⚠️ In rare cases, the detail is used to give more information about an expected, required value or an resource id to allow a deeper error handling on consumer side. In this case, an normal formatted detail about the field goes along with this information to give more context and to still be processed in a generic way if wished.

Non-exhaustive list of examples:

On user backup update:

{
"version": "conflict",
"expected_version": "1"
}

On any authenticated routes:

{
"acr": "forbidden",
"required_acr": "2"
}