apps.patrol docs

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

CodeStatusMeaningWhat to do
unauthorized401The key is missing, wrong, rotated or revoked.Check the key. Do not retry unchanged.
invalid_request400, 422The 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_large422More than 100 events in one request.Split the batch.
payload_too_large413The request body is over 512 KB.Send fewer or smaller events.
invalid_shop422Shops API: shop is missing or not a *.myshopify.com domain.Send the shop's myshopify.com domain.
rate_limited429Too many requests with this key in the current minute.Wait for Retry-After seconds, then retry.
quota_exceeded429The organization's monthly event allowance is used.Stop sending until next month, or change plan. Retrying does not help.
plan_required402REST 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.

CodeMeaning
invalid_eventThe array item is not a JSON object.
missing_event_idevent_id is missing or empty.
invalid_event_idevent_id is not a string, or longer than 200 characters.
missing_namename is missing or empty.
invalid_namename is longer than 100 characters or uses characters other than a-z 0-9 _ . : -.
missing_shopshop is missing or empty.
invalid_shopshop is not a *.myshopify.com domain.
invalid_propertiesproperties is not an object, has more than 50 keys, is nested more than 3 levels, or is over 8 KB.
invalid_timestampoccurred_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 5xx responses with exponential backoff, for example 1, 2, 4, 8 and 16 seconds.
  • On 429 rate_limited, wait for Retry-After.
  • Do not retry other 4xx responses without changing the request.
  • Keep the same event_id when 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.