Guide
Status codes
Five-digit status codes describe the result of a request and of every task in it. The same table is available from the API at GET /v1/appendix/errors.
Request and task level
The top-level status_code describes the request as a whole: authentication, balance, rate limits and the shape of the body. When it is 20000, look at each task: one task can fail (for example with 40503 for an invalid ASIN) while the others succeed. tasks_error counts the failed tasks.
Codes in the 2xxxx range mean success, 4xxxx a problem with the request, 5xxxx a problem on our side. A code returned for the whole request comes with the HTTP status shown first in the table; the same code on a single task arrives inside a successful HTTP 200 response (for example 400 / 200).
All status codes
| Code | Message | HTTP | Level | When |
|---|---|---|---|---|
| 20000 | Ok. | 200 | Request / task | The request, or the individual task, was processed successfully. |
| 20100 | Task Created. | 200 | Task | task_post accepted the task. Collect the result later with tasks_ready and task_get, or receive it with a webhook. |
| 40000 | Bad Request. | 400 / 200 | Request / task | The body is not valid JSON or does not have the expected shape (for example, not an array of task objects, or more than one task for live). Also returned with HTTP 413 for bodies larger than 1 MiB and with HTTP 405 for a wrong HTTP method. As a task-level code (HTTP 200) it means the task cannot be carried out as asked, for example because the account already has the maximum number of API keys or monitored products. |
| 40001 | Too many tasks in one request (max 100). | 400 | Request | A POST body contains more task objects than allowed. |
| 40100 | Authentication failed. | 401 | Request | The Authorization header is missing or malformed, or the login and API key do not match. |
| 40101 | API key revoked. | 401 | Request | The API key was revoked. Use another active key or create a new one. |
| 40102 | Account disabled. | 401 | Request | The account is disabled. Contact support. |
| 40200 | Payment Required. Insufficient balance. | 402 / 200 | Request / task | The balance does not cover the cost. When no task of a request can be paid for, the whole request fails with HTTP 402; otherwise only the tasks that cannot be paid for fail. Contact us to add balance, then retry. |
| 40202 | Rate limit exceeded. | 429 | Request | Too many requests or tasks per minute for this account, or too many access requests from one IP address. The Retry-After header says how many seconds to wait. |
| 40400 | Not Found. | 404 / 200 | Request / task | Unknown endpoint, or an unknown task, key or subscription id. |
| 40401 | Task not ready yet. | 200 | Task | task_get was called before the task completed. Retry later or use webhooks. |
| 40402 | Product not found on Amazon. | 200 | Task | The product page does not exist on that marketplace. The task is not charged. |
| 40501 | Invalid field: `<name>`. | 400 / 200 | Request / task | A field has a wrong type, format or value; the message names the field, for example "Invalid field: `priority`." |
| 40502 | Unknown marketplace. | 200 | Task | The marketplace is not one of the 12 supported codes or their aliases. |
| 40503 | Invalid ASIN. | 200 | Task | The ASIN does not match ^[A-Z0-9]{10}$ after uppercasing. |
| 40600 | Feature not available on your plan. | 403 | Request | The requested feature is not enabled for this account. |
| 50000 | Internal error. | 500 | Request | Unexpected server error. The request can be retried; contact support if it persists. |
| 50301 | Source temporarily unavailable. Try again later. | 200 | Task | The data source could not be read (blocked, unavailable or too slow). The task is not charged: its cost is refunded automatically. Try again later. |
Handling errors
- 40000–40001, 40501–40503: fix the request — the message names the problem. Retrying the same request will fail again.
- 40100–40102: check the login and key, or use another active key. See Authentication.
- 40200: the balance is too low. To add balance, contact us. Monitoring subscriptions pause and resume automatically once balance is added.
- 40202: wait for the number of seconds in the
Retry-Afterheader, then retry. See Rate limits. - 40401: the task is still running — call task_get again later or use webhooks.
- 40402: the product does not exist on that marketplace. The task is not charged.
- 50000, 50301: temporary. Retry with exponential backoff (for example after 5, 30 and 120 seconds). Unused charges are refunded automatically.