Errors | Modular DS | API documentation

The API uses standard HTTP status codes: 2xx for success, 4xx for a problem with the request, 5xx for a problem on our side. Every error answers a JSON:API error document with Content-Type: application/vnd.api+json.

The error document

{
  "errors": [
    {
      "status": "422",
      "title": "Validation Error",
      "detail": "The page.size field must not be greater than 50.",
      "source": { "parameter": "page[size]" }
    }
  ],
  "jsonapi": { "version": "1.1" }
}

Member	Always present	Meaning
`status`	Yes	The HTTP status code, as a string
`title`	Yes	A short summary of the kind of error
`detail`	When there is a message	What went wrong in this request, in English
`source.parameter`	Validation and query errors	The offending field or query parameter, in bracket form (`page[size]`, `filter[core_version]`)

A validation failure lists one error object per problem, so a single response can carry several entries in errors.

Status codes

Code	`title`	When
`400`	`Invalid Query Parameter`	An unknown filter, sort or include. `source.parameter` is `filter`, `sort` or `include`, and `detail` lists the allowed values. See Filtering and sorting.
`401`	`Unauthenticated`	The token is missing, malformed, unknown or expired. See Authentication.
`403`	`Forbidden`	A read-only token tried to write, your role does not allow the action, or the organization’s Public API is disabled or out of quota. See Organizations.
`404`	`Not Found`	The resource does not exist, or belongs to another organization.
`409`	`Error`	The request conflicts with the organization’s state, for example creating backups with the storage quota exhausted.
`422`	`Validation Error`	A body field or query value is invalid, `page[size]` is above 50, or the query uses a parameter the API does not accept.
`429`	`Error`	Too many requests. See Rate limits.
`500`	`Server Error`	Something failed on our side. Retrying later is safe for reads.

Handling errors

Branch on the HTTP status and on status, not on detail: the wording of detail can improve over time.
Show detail to a person when it helps: it is written to be read.
Use source.parameter to point at the field to fix.