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.
402	The free tier's monthly sending allowance is exhausted. Upgrade to a paid plan to keep sending; inbound mail is always received.
403	The token lacks the scope this operation requires (error code missing_scope), or the request breaks a JSON:API protocol rule (client_generated_id, unsupported_relationship_update). Never returned for a record that belongs to another account — that case is a 404.
404	The resource does not exist, or it belongs to another account. The two cases return the same status, error code and detail by design, so the error document does not confirm that an identifier is in use.
	The request conflicts with the endpoint or current state. Branch on the error code: conflict — 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; agent_category_conflict — the agent_id names an identity already bound to the other kind of mail (one agent identity sends either transactional or marketing mail, never both; an identity dormant for 30 days may rebind). (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 request was rate limited. Branch on the error code: rate_limited means the account exceeded its API rate limit, and agent_throttled means the agent named by agent_id has a restricted sender reputation and has exhausted the send allowance for its tier.