Errors

Errors use the Problem Details format, with Content-Type: application/problem+json:

{
  "type": "/errors/not-found",
  "title": "Item not found",
  "status": 404,
  "detail": "No item with id or slug 'nope'.",
  "instance": "/v1/items/nope"
}

Branch on status and type; title and detail are meant for people and may change.

| Status | type | Meaning | |---|---|---| | 400 | /errors/token-in-url | The key was sent in the URL; send it in the Authorization header | | 401 | /errors/unauthorized | No key, a malformed key, or a revoked one | | 403 | /errors/banned | The key, the account or the network address is suspended; detail says until when | | 404 | /errors/not-found | No such id, slug, version or route | | 405 | /errors/method-not-allowed | The API is read-only: only GET | | 422 | /errors/validation | A parameter is invalid; errors lists each one with param and message | | 422 | /errors/not-priceable | Asked for the price of something that is not food or drink | | 429 | /errors/rate-limited | Too many requests; wait Retry-After seconds | | 500 | /errors/internal | Our fault; quote the trace_id if you report it | | 503 | /errors/service-unavailable | Briefly unavailable; retry after Retry-After |

When requests fail with 5xx or time out, status.taverndata.com shows whether the API is having an incident.

A validation error names the parameter:

{
  "type": "/errors/validation",
  "status": 422,
  "detail": "Unknown perk 'wine'; expected one of starter, meat, vegetables, …",
  "errors": [{ "param": "perks", "message": "Unknown perk 'wine'; expected one of starter, meat, vegetables, …" }]
}