Errors and status codes

Status codes

API V1 returns standard HTTP status codes:

Code	Name	Meaning
`200`	OK	The request succeeded.
`304`	Not Modified	The resource hasn't changed since your last request.
`400`	Bad Request	The request is malformed. The error body has the details.
`401`	Unauthorized	The API key is missing or invalid.
`403`	Forbidden	The API key doesn't have the permission this endpoint needs.
`404`	Not Found	The URL is wrong, or the resource (for example a project) doesn't exist.
`406`	Not Acceptable	The requested response format isn't supported.
`422`	Unprocessable Entity	The request is well formed but has invalid values.
`429`	Too Many Requests	You exceeded the rate limit. Wait for the seconds in `Retry-After`.
`500`	Internal Server Error	Something went wrong on our side. Contact [email protected] if it persists.

Error bodies

Error bodies are JSON. Most errors describe the rejected input in validationErrors:

{
  "error": null,
  "validationErrors": [
    {
      "field": "token",
      "errors": [
        {
          "code": "authentication.token.invalid",
          "description": "The token is invalid!",
          "parameters": {}
        }
      ]
    }
  ]
}

Errors that aren't about a specific field use error instead:

{
  "error": {
    "code": "…",
    "description": "…",
    "status": "…"
  },
  "validationErrors": null
}

Use code in your error handling; description is meant for people. A few errors, such as a missing resource or an unexpected server error, return a short body with a message field instead.

Rate limit headers

Responses carry the current rate limit budget of your workspace:

Header	Meaning
`X-RateLimit-Limit`	Size of the request budget.
`X-RateLimit-Remaining`	Requests left right now.
`X-RateLimit-RefillRate`	Rate at which the budget refills.
`Retry-After`	On `429`: seconds to wait before you retry.