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
`code`	Business refusals	A stable, machine-readable error code such as `site_incomplete_connection`, equal to `title`. Safe to branch on
`source.parameter`	Validation and query errors	The offending field or query parameter, in bracket form (`page[size]`, `filter[core_version]`)

A business refusal looks like this:

{
  "errors": [
    {
      "status": "400",
      "title": "site_incomplete_connection",
      "detail": "Please, you must connect your site first",
      "code": "site_incomplete_connection"
    }
  ],
  "jsonapi": { "version": "1.1" }
}

Other codes you can meet are team_not_deleted_because_has_site_exception (deleting a team that still holds websites) and site_without_repository_user (issuing a login link for a website with no WordPress user synced).

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.
`400`	The error code, for example `site_incomplete_connection`	A business rule refused the request, for example acting on a website that is not connected or deleting a team that still holds websites. `code` carries the same value as `title`, and `detail` describes the refusal.
`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. `detail` is `Resource not found.` when the id matches nothing, and other text (for example `Not Found`) when the API hides a resource you cannot see.
`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 and, when it is present, on code. Do not branch on detail: its wording can improve over time and differs between errors of the same status.
Show detail to a person when it helps: it is written to be read.
Use source.parameter to point at the field to fix.