Conventions

Errors and status codes

Every error has the same shape, whatever the status. Switch on error.code, not on the HTTP status alone and never on the message: that may be reworded.

The shape

Name	Type	Default	Description
`error.code` required	`unauthorized \| forbidden \| not_found \| invalid_request \| method_not_allowed \| conflict \| rate_limited \| internal`	-	Stable machine code. Switch on this, never on the message.
`error.message` required	`string`	-	Human readable explanation in English. May be reworded at any time.
`error.details` optional	`object`	-	Extra context. For invalid_request this carries `params`, one entry per bad parameter.
`request_id` required	`string`	-	The X-Request-Id of this response. Quote it when you report a problem.

400 invalid_request

{
  "error": {
    "code": "invalid_request",
    "message": "1 parameter is wrong: limit.",
    "details": {
      "params": [
        {
          "param": "limit",
          "message": "must be 100 or less"
        }
      ]
    }
  },
  "request_id": "9f1c2b4a-7e3d-4a10-9c2f-6b8d1e5a0c33"
}

The codes

These are all values of error.code. A new code is a change to the specification and goes in the changelog.

error.code	HTTP	Meaning
`unauthorized`	`401`	No token, an unknown token or a revoked token.
`forbidden`	`403`	A valid token that may not do this: a missing scope, a suspended organisation, or another organisation's event.
`not_found`	`404`	The endpoint exists, but what you ask for does not.
`invalid_request`	`400`	The request is wrong: an unknown value, a bad cursor, a body that is not JSON.
`method_not_allowed`	`405`	The path exists, but not with this method. `Allow` says which do.
`conflict`	`409`	The request does not fit the state of what it addresses.
`rate_limited`	`429`	Over the per-minute limit or the daily quota. `Retry-After` says how long to wait.
`internal`	`500`	Our fault. The `request_id` is what we need to find it.

With invalid_request, error.details.params lists every parameter that is wrong, with the reason, all at once.

Every status in the specification

The reference says per endpoint which of these it can give.

Status	Meaning
`400`	The request is wrong. `error.details.params` names every bad parameter.
`401`	No token, or a token we do not know.
`403`	The token is valid but does not carry the `read` scope, or the organisation is suspended.
`404`	No such resource.
`409`	This event does not use external ticketing.
`429`	Over the per-minute limit or the daily quota. `Retry-After` says how long to wait.
`500`	Something went wrong on our side. Quote `request_id`.

Reporting an error

Every response, good or bad, has an X-Request-Id header, and an error carries it in the body as request_id too. Include it when you mail us; then we find the request. See Support.

Updated 2026-10-17