Errors

Errors are JSON:API error documents with a stable shape across every endpoint — branch on the HTTP status code and the machine-readable code, read the human explanation from detail (its wording is not part of the contract).

Error document

The body is an errors array. Validation errors additionally carry a source.pointer locating the offending attribute.

{
  "jsonapi": { "version": "1.1" },
  "links": { "describedby": "https://api.minimailer.app/openapi.yaml" },
  "errors": [
    {
      "status": "422",
      "code": "validation_failed",
      "detail": "The name field is required.",
      "source": { "pointer": "/data/attributes/name" }
    }
  ]
}

Error catalogue

The shared responses every endpoint can return.

Status	Description
400	The include or fields query parameter is not supported (unknown relationship, over-deep include, or unknown sparse-fieldset type or field).
401	Authentication is required.
403	The authenticated token does not have permission to perform this action.
404	The requested resource could not be found.
	The request conflicts with the endpoint or current state: the document's resource type does not match the endpoint, its id does not match the resource being updated, or an idempotency key was reused with a different payload. (Creating with a client-generated id and updating relationships on an endpoint that does not support them return 403 instead.)
	The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains.
415	The request Content-Type must be application/vnd.api+json, with no media type parameters other than profile (ext is rejected — no JSON:API extensions are supported — as is any other parameter such as charset).
422	The request document failed validation.
429	The caller exceeded the API rate limit.