Errors

A request that the API understood but cannot carry out returns a DomainError body:

{
  "code": "household.display-name-taken",
  "details": {}
}

code is stable and names the domain it comes from; switch on it, not on the status alone. details carries only the ids involved, and is often empty.

Status	Meaning	What to do
`400`	The request is not valid: a malformed id, week or field.	Fix the request. Retrying it unchanged fails the same way.
`401`	No valid session.	Sign in again.
`403`	The caller may not do this, or the request origin is not allowed.	Do not retry; the person’s role does not allow it.
`404`	The subject does not exist in your household.	Do not retry. A subject in another household is also a `404`.
`409`	The request conflicts with the current state, such as superseding a version that is no longer current, or it matches more than one thing.	Read the current state, then decide again.
`422`	The payload is not valid for this operation.	Fix the payload.
`429`	Too many requests.	Wait, then retry.
`500`	The request failed on our side.	Retry later.

A 500 body carries a correlationId instead of a code:

{
  "correlationId": "4f1c2e0a-6b1e-4c8a-9a8e-2f6b1d3c7e90",
  "message": "Something went wrong."
}

Include the correlationId when you report the problem; it finds the request in our logs.

Get started

API reference