Errors
Error codes, what each means and when to retry.
Errors from the ingestion API (/v1) and the REST API (/api/rest/v1) share one shape. Branch on the HTTP status and code; message is for people and may change.
{
"error": {
"code": "rate_limited",
"message": "Too many requests: the limit is 600 per minute per key. Retry after 12 seconds.",
"docs": "https://www.apps-patrol.com/docs/errors#rate_limited"
}
}
Request errors
| Code | Status | Meaning | What to do |
|---|---|---|---|
unauthorized | 401 | The key is missing, wrong, rotated or revoked. | Check the key. Do not retry unchanged. |
invalid_request | 400, 422 | The body is not valid JSON, a required parameter is missing, events is not an array, or every event in the request was invalid. | Fix the request. For events, read errors. |
batch_too_large | 422 | More than 100 events in one request. | Split the batch. |
payload_too_large | 413 | The request body is over 512 KB. | Send fewer or smaller events. |
invalid_shop | 422 | Shops API: shop is missing or not a *.myshopify.com domain. | Send the shop's myshopify.com domain. |
rate_limited | 429 | Too many requests with this key in the current minute. | Wait for Retry-After seconds, then retry. |
quota_exceeded | 429 | The organization's monthly event allowance is used. | Stop sending until next month, or change plan. Retrying does not help. |
plan_required | 402 | REST API: the organization's plan does not include it. | Change plan. |
Tell rate_limited and quota_exceeded apart by code: both use status 429, but only the first has a Retry-After header.
Per-event codes
These appear in the errors array of an Events API response, next to the event's index.
| Code | Meaning |
|---|---|
invalid_event | The array item is not a JSON object. |
missing_event_id | event_id is missing or empty. |
invalid_event_id | event_id is not a string, or longer than 200 characters. |
missing_name | name is missing or empty. |
invalid_name | name is longer than 100 characters or uses characters other than a-z 0-9 _ . : -. |
missing_shop | shop is missing or empty. |
invalid_shop | shop is not a *.myshopify.com domain. |
invalid_properties | properties is not an object, has more than 50 keys, is nested more than 3 levels, or is over 8 KB. |
invalid_timestamp | occurred_at is not ISO 8601, more than 7 days old, or more than 1 hour in the future. |
Webhook endpoint
/webhooks/shopify/… is called by Shopify and answers with a status only: 200 accepted, 401 signature mismatch or no client secret saved, 404 unknown app, 400 body is not JSON.
Retrying
- Retry network failures and
5xxresponses with exponential backoff, for example 1, 2, 4, 8 and 16 seconds. - On
429 rate_limited, wait forRetry-After. - Do not retry other
4xxresponses without changing the request. - Keep the same
event_idwhen you retry an event.
Getting help
Include the endpoint, the status, the response body and the time of the request when you contact support at businessandadministration@it-patrol.tech. Never send your key.