HTTP response codes

Every response comes with an HTTP status code that tells you whether the request succeeded. Codes in the 2xx range mean success, 4xx codes mean a problem with the request, and 5xx codes mean a problem on our side. See the full list of HTTP status codes on MDN.

Error codes

Status code	Description
400 Bad Request	The request is incorrect. Check that the parameters match the format described on the endpoint page.
401 Unauthorized	The API key is missing, invalid or expired.
403 Forbidden	The API key's scope doesn't allow this request (a write with a Read Only key, a read with a Write Only key), or the request comes from an IP address that isn't whitelisted. See Token authentication.
404 Not Found	The resource you requested doesn't exist.
429 Too Many Requests	You have reached the rate limit.
500 Internal Server Error	Something unexpected happened on our side. Try again, or contact support if it keeps happening.
502 Bad Gateway	A server between you and the API received an invalid response. Try again.
504 Gateway Timeout	A server between you and the API didn't get a response in time. Try again.

Errors any endpoint can return

401, 429, 500, 502 and 504 can come from any endpoint, so endpoint pages don't repeat them. A missing or invalid API key returns 401 Unauthorized with this body:

{
  "detail": "Invalid token."
}

Check the Authorization: Token <your_64_char_api_key> header. See Token authentication.

Handle errors by status code

Status	Meaning	What to do
200 / 201	Success	Continue.
400	Validation error	Read the error body, fix the request. Don't retry without changes.
401	Unauthorized	Check the API key, and whether it has expired.
403	Forbidden	Check the API key's scope (a Read Only key can't create, change or delete; a Write Only key can't read) and the IP whitelist.
404	Not found	The record you refer to doesn't exist. Create it first.
429	Rate limited	Wait and retry. See Rate limits.
500	Server error	Retry with backoff. Contact support if it keeps happening.

How error bodies look is described in Error response formats, and the errors integrations hit most often in Common errors.