Errors, idempotency, retries and rate limits

Before retrying a failed request

Use this page when an API request, inbound webhook, platform handoff or ticket export webhook fails and you need to decide whether to retry, change the request or stop. Start by classifying the failure; retries are safe only when the same logical request, source identifiers and payload meaning are preserved.

• Use placeholder values only; never paste real API keys, webhook secrets, tokens or customer data into documentation examples.
• Keep `Idempotency-Key` stable only for the same logical request and change it when the payload meaning changes.
• Respect `Retry-After`, `retry_after_seconds` and provider rate-limit diagnostics before retrying.

Triage an API or webhook failure

Follow the path `Failed request → Status and error code → Idempotency decision → Backoff or payload fix → Endpoint-specific next step`.

1. Open the endpoint-specific page for the failed request: Scanner results API, Inbound email webhook, API ticket export webhooks or Extension and platform handoffs. Result: the auth header, payload schema and accepted response are visible before you retry.
2. Read the HTTP status, JSON message, error code and response headers before sending another request. Result: a permanent auth, validation or signature failure is not retried like a transient outage.
3. For `401 UNAUTHORIZED`, verify `Authorization`, `X-Scanner-Secret`, `X-Email-Webhook-Secret`, `X-Shopify-Hmac-Sha256` or `X-WebRiskOps-Signature` against the endpoint rules. Result: missing, invalid or unconfigured secrets are fixed before another payload is sent.
4. For `403 FORBIDDEN`, verify the bearer token ability, such as `browser-extension:evidence-upload`, `cms-plugin:diagnostics-upload` or `shopify-app:diagnostics-upload`. Result: platform diagnostics do not retry with a token that cannot write that route.
5. For `422 VALIDATION_FAILED` or `INVALID_PAYLOAD`, fix missing fields, enum values, report/project mismatches, unsafe scopes or malformed URLs. Result: the same invalid body is not replayed.
6. For `409 IDEMPOTENCY_CONFLICT`, stop the request and compare the previous payload meaning with the new payload. Result: the same `Idempotency-Key` is not reused for a different logical action.
7. For `429 RATE_LIMITED` or `WEBHOOK_RATE_LIMITED`, read `Retry-After`, `retry_after_seconds`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` when present. Result: the caller waits for the documented retry window instead of increasing pressure.
8. For `5xx`, connection failures or ticket export `retry_scheduled` state, retry with exponential backoff and the same source identifiers. Result: transient failures can recover without duplicate scanner pages, messages, platform handoffs or provider tickets.
9. For `SIGNATURE_INVALID` or `WEBHOOK_SIGNATURE_INVALID`, fix the shared secret, timestamp, nonce, raw body or provider HMAC calculation before retrying. Result: replayed or unsigned payloads do not create downstream work.
10. Continue to Request and response examples or Automation code examples after the failure class is clear. Result: the next request uses placeholder-safe examples and the correct retry rule.

Map status codes and error codes

Use status codes for the first decision, then use the endpoint page for field-level detail.

• `202 Accepted`, `201 Created`, `204 No Content` and 2xx webhook responses mean the request was accepted; stop retrying that attempt.
• `401 UNAUTHORIZED` means a bearer token, shared secret or HMAC signature is missing, invalid or not configured.
• `403 FORBIDDEN` means an authenticated token lacks the required Sanctum ability or project/report permission.
• `409 IDEMPOTENCY_CONFLICT` means the same `Idempotency-Key` was reused for a different payload meaning.
• `422 VALIDATION_FAILED` or `INVALID_PAYLOAD` means the body, route parameters, headers or enum values must change before retrying.
• `429 RATE_LIMITED`, `WEBHOOK_RATE_LIMITED` or provider `rate_limited` means wait for `Retry-After` or `retry_after_seconds`.
• `503 Service unavailable` can mean a required provider secret, such as the scanner, email or Shopify webhook secret, is not configured.

Configure idempotency and retry behavior

Idempotency and retry state must stay tied to one source event.

• Use `Idempotency-Key` for scanner retries, client retry logs and automation examples when the same logical request may be resent.
• Outbound ticket export webhooks use `X-WebRiskOps-Idempotency-Key`, payload `idempotency_key` and persisted `idempotency_fingerprint`.
• Ticket export execution records `retry_after_seconds`, `provider_status`, `blockedReasonCode` and `retry_scheduled` status when a provider returns a rate limit or retryable state.
• Keep source identifiers stable: scanRunId for scanner postbacks, event_id for inbound email, provider message IDs for delivery events, and ticket export source fingerprints for provider tasks.
• Treat `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` as provider or edge headers when present; do not invent them when a response does not include them.
• Use exponential backoff for transient 429, 5xx and connection failures, and stop when validation, auth, signature or unsafe URL errors repeat.

Ready and blocked retry states

Retry only when the next request is expected to produce a different safe outcome.

• Retry ready means the same source event, same payload meaning and same idempotency key are being resent after a transient failure.
• Backoff ready means `Retry-After` or `retry_after_seconds` has elapsed before the next attempt.
• Payload fix ready means a 422 request has been corrected before retrying.
• Auth fix ready means the token, shared secret, provider HMAC or webhook signing secret has been configured or rotated.
• Retry blocked means `IDEMPOTENCY_CONFLICT`, `SIGNATURE_INVALID`, `WEBHOOK_SIGNATURE_INVALID`, `generic_webhook_validation_failed`, `generic_webhook_auth_failed` or unsafe URL diagnostics still apply.
• Duplicate blocked means the same event, scanRunId, event_id or ticket export source already reached a terminal accepted state.

Continue after retry triage

After classifying the failure, return to the endpoint page that produced it. Use Authentication and headers for token or signature failures, Request and response examples for placeholder-safe payloads, Automation code examples for bounded retry snippets, and API ticket export webhooks when provider retry state comes from outbound ticket delivery.