Errors and Rate Limits

Rate Limits

Back off and retry later when you get a 429 or 503.

Error Formats

Most errors look like this:

{
  "success": false,
  "message": "You cannot go beyond page 750. Please narrow your search terms.",
  "code": null
}

code is an id for unexpected errors, include it if you report the problem.

A few errors use a different shape:

Status Body
403 {"success": false, "reason": "Access Denied"}, the reason may include more detail, ex: Access Denied: Must be logged in
404 {"success": false, "reason": "not found"}
422 Validation failures from creating or updating something use {"errors": {"field": ["is invalid"]}}
412 Uploads, see POST /uploads.json

Errors from Cloudflare (5xx codes above 520) and some 503s are HTML, not JSON.

Status Codes

Status Meaning
200 Success
201 Created
204 Success, with no response body. Common for updates and deletes.
400 Bad request, or the feature isn't available
401 Authentication failed, see Authentication
403 Access denied. Can also mean the request is missing a user agent.
404 Not found
405 The method isn't allowed for the URL. Switching between POST, PATCH, and PUT usually fixes it.
406 The format isn't supported. Most endpoints only support .json (and HTML).
410 Invalid pagination, like going beyond page 750. See Pagination.
412 An upload was invalid or a duplicate
413 The request was too large
422 Invalid input. Also used for searches that are too complex, have too many tags, or time out, and for GET parameters over 16 KB.
429 Rate limited
500 Server error. A database timeout also returns this.
502 Cloudflare couldn't reach e621
503 Rate limited, or e621 is unavailable
520, 522, 524, 525 Cloudflare errors connecting to e621