Start

Errors

One shape for every error, with a code to branch on and a detail for your logs.

The shape

JsonError

{
  "errors": [
    {
      "code": "string, stable, branch on it",
      "detail": "string, English, for logs, never shown to users",
      "source": {
        "pointer": "the refused path parameter, when there is one"
      }
    }
  ]
}

Branch on code. It is stable and machine-readable, and new codes are only ever added. detail is English prose for a log line; never render it to your users. source.pointer appears on a refused path parameter and points at it.

Every code /v1 returns

Status	Code	When	What to do
401	`unauthorized`	No key on the request.	Send the bearer.
401	`api_key_invalid`	Not a key immit issued.	Check the paste.
401	`api_key_revoked`	Revoked in the console.	Use the key that replaced it.
401	`api_key_suspended`	Suspended by a person at immit.	Read the email, write back.
404	`not_found`	No entry, spelling or case variant matches the headword.	Search instead; the user may have met an inflection the search resolves.
429	`rate_limited`	The burst a minute is used.	Wait `retry-after` seconds.
429	`quota_exceeded`	The day's quota is used.	Wait for midnight UTC or move up a tier.
422	`invalid_param`	A parameter is not what the spec says: a lang of fra, a limit that is not a number. A limit over 25 is capped, not refused.	Read `detail`, and `source.pointer` when it names the parameter.
5xx	varies	immit's fault.	Retry with backoff; the status page says if it is more than a blip.

404 · application/json

{
  "errors": [
    {
      "code": "not_found",
      "detail": "Not Found"
    }
  ]
}

422 · application/json

{
  "errors": [
    {
      "code": "invalid_param",
      "source": {
        "pointer": "/lang"
      },
      "detail": "Invalid value for enum"
    }
  ]
}

Unknown codes

A client that meets a code it does not know falls back to generic copy for its status. Codes are added under /v1 without a version bump, like fields.

The shape

JsonError

{
  "errors": [
    {
      "code": "string, stable, branch on it",
      "detail": "string, English, for logs, never shown to users",
      "source": {
        "pointer": "the refused path parameter, when there is one"
      }
    }
  ]
}

Every code /v1 returns

Status	Code	When	What to do
401	`unauthorized`	No key on the request.	Send the bearer.
401	`api_key_invalid`	Not a key immit issued.	Check the paste.
401	`api_key_revoked`	Revoked in the console.	Use the key that replaced it.
401	`api_key_suspended`	Suspended by a person at immit.	Read the email, write back.
404	`not_found`	No entry, spelling or case variant matches the headword.	Search instead; the user may have met an inflection the search resolves.
429	`rate_limited`	The burst a minute is used.	Wait `retry-after` seconds.
429	`quota_exceeded`	The day's quota is used.	Wait for midnight UTC or move up a tier.
422	`invalid_param`	A parameter is not what the spec says: a lang of fra, a limit that is not a number. A limit over 25 is capped, not refused.	Read `detail`, and `source.pointer` when it names the parameter.
5xx	varies	immit's fault.	Retry with backoff; the status page says if it is more than a blip.

404 · application/json

{
  "errors": [
    {
      "code": "not_found",
      "detail": "Not Found"
    }
  ]
}

422 · application/json

{
  "errors": [
    {
      "code": "invalid_param",
      "source": {
        "pointer": "/lang"
      },
      "detail": "Invalid value for enum"
    }
  ]
}