Errors and limits
Status codes, headers and limits.
Error envelope
Errors raised by the platform itself use this JSON envelope. Other statuses come from the model, with its own body.
Example error
{"is_success": false, "message": "No search tokens left. Buy more to continue.", "data": null}Status codes
| Status | Meaning |
|---|---|
| 400 | Bad input: the file is missing, cow_id is missing or invalid, top_k, limit or offset is not a whole number in range (an empty value such as top_k= counts), or Content-Length is invalid. |
| 401 | The X-API-Key header is missing. |
| 402 | No tokens of the needed type are left. Buy more tokens to continue. |
| 403 | The API key is invalid or revoked, or your account is suspended. |
| 405 | Wrong HTTP method for the endpoint. The Allow header lists the right one. |
| 413 | The upload is larger than 20 MB. |
| 415 | The enroll or identify body is not multipart/form-data. |
| 429 | The rate limit or the concurrent-request limit was reached. Wait the number of seconds in the Retry-After header, then try again. |
| 502 | The model could not be reached, timed out, or sent a response that could not be processed safely. No token is charged. |
Every failed call is free.
Response headers
| Header | Meaning |
|---|---|
| X-Request-Id | A unique id for the call, sent on every call with a valid key and the right HTTP method (not on 401, 403 or 405). Quote it when you contact support. |
| X-Tokens-Remaining | Your remaining tokens of that call's type, on enroll (enroll tokens) and identify (search tokens) only, including when the call failed or was refused. |
| X-Sandbox | true on every answer to a sandbox key. Never present on a live call. |
| Retry-After | On 429: the number of seconds to wait before trying again. |
| Allow | On 405: the HTTP method the endpoint accepts. |
Limits
- Rate: 60 requests per minute, counted across all four endpoints. The count restarts at the start of each minute.
- Concurrency: 2 requests at the same time. The service also limits calls in progress across all accounts, so a 429 can come before you reach your own limit.
- Upload size: 20 MB per photo.
When you reach a limit you get 429 with a Retry-After header. Spread calls out and retry after that many seconds.