Errors and limits
Every failed call gets the same error envelope. This page lists each error code with what to do about it, then the rate limits and the photo limits you will meet first.
Envelope
A failure answers with a JSON body holding one error object. The same id is also in the X-Request-Id response header.
{
"error": {
"code": "validation_failed",
"message": "The request has invalid fields.",
"details": [
{
"field": "priority",
"code": "invalid_value",
"message": "This value is not allowed."
}
],
"request_id": "req_01H00000000000000000000000"
}
}Branch on code, never on message. Messages may be reworded, and codes may not alter, only be added. details has one entry for each field with a problem and is left out when there are none. Quote the request_id, which starts req_, when you contact support.
A 400 is a request the server could not read. A 422 is a request it could read but refuses: invalid fields, an expired updated_since window, a rejected upload or a reused Idempotency-Key.
Access codes
The retry column says whether the same request can succeed later. Backoff means waiting a little longer after each failure, with some randomness.
Request codes
Refusals
Uploads and repeats
Fixing by a step
Two refusals are fixed by a step, not by waiting. After precondition_failed, read the defect again and send its latest ETag in If-Match. After upload_missing, finish sending the file and confirm the photo again.
Detail codes
A details[].code says why a field or an action was refused. These values are frozen, and more are only added over time. These come with validation_failed.
These come with upload_rejected.
Availability codes
These come with create_not_available.
Action codes
These come with action_not_available.
Limits
Each key may make 600 reads and 120 writes a minute. A GET or HEAD is a read and every other method is a write, and the two are counted apart. A company's keys together may make 1,800 reads and 360 writes a minute, so three busy keys fit before they start to crowd each other. Bursts up to the per-minute number are allowed.
Every response to an identified call carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. They describe the limit that binds at that moment, the key's or the company's, and RateLimit-Reset is the whole seconds until it is full again.
Past a limit the answer is 429 rate_limited with Retry-After, the seconds to wait. Wait that long, then send the same request again.
Repeated failed authentication from one address is refused with 429 for a while, so fix a wrong key instead of retrying it. A call to a path the API does not have answers route_not_found and is not counted in a key's usage in Settings > Public API.
Photo limits
A photo is image/jpeg, image/png, image/webp, image/heic or image/heif, from 1 byte to 25 MB (26,214,400 bytes). The file you send must be exactly the size you declared.
The upload link lasts 15 minutes. A confirmed photo is listed with download links that stop working an hour after they are made, so ask again instead of keeping one.
Every endpoint lists the errors it can return in the API reference.