Error envelope
Read the error code and retain the request identifier.
The response separates a machine-readable condition from a human-readable explanation. Preserve that distinction in application logic so a wording change does not alter how your integration handles the failure.
Example errorJSON
{
"error": {
"code": "VALIDATION_FAILED",
"message": "The request body is invalid.",
"requestId": "57780f31-3f41-4485-b9de-87858e145116",
"details": {
"issues": [
{ "path": "currency", "message": "Expected USD" }
]
}
}
}code- Use this machine-readable value for branching, metrics and alerts.
message- Human-readable diagnostic context. Do not parse it for application logic.
requestId- Store this value with your source operation and provide it when contacting support.
details- Optional structured context such as validation paths. Its fields depend on the error code.
Status guide
Retry only when the condition is transient.
| Status | Meaning | Integration action |
|---|---|---|
| 400 | Malformed input or required header missing | Correct the request. Do not retry unchanged. |
| 401 | Credential missing, invalid, expired or revoked | Stop and restore a valid credential. |
| 403 | Authenticated but not permitted | Check tenant status and assigned scope; do not broaden scope automatically. |
| 404 | Route or tenant-owned resource not found | Verify the path and opaque identifier. Do not probe other tenants. |
| 409 | Idempotency, state or version conflict | Inspect the error code; read current state before deciding whether to retry. |
| 413 | Request exceeds the 12 MiB boundary | Reduce the request according to the endpoint contract. |
| 415 | Unsupported media type | Send the documented Content-Type. |
| 422 | Well-formed request fails semantic validation | Correct fields or referenced resources. Do not retry unchanged. |
| 428 | If-Match is required | Read the resource and retry with its current ETag. |
| 429 | Request rate was limited | Honor Retry-After when this status is returned. |
| 500 | Unexpected server failure | Retry with bounded backoff and the same idempotency key. |
| 503 | Dependency or stored operation is unavailable | Retry with bounded backoff; alert if the condition persists. |
Do not design around an invented request allowance. If a route returns 429, follow its headers. Expected traffic is reviewed during developer onboarding.
Retry decision
Keep a retry connected to the original operation.
A retry repeats the same logical request; it is not a new Shopify order or adjustment. Read the idempotency conventions alongside the status guide before choosing whether to try again.
- 01
Classify the failure
Validation, authentication, permission and most not-found failures require a correction, not a retry.
- 02
Keep the same idempotency key
For a transient mutation failure, retry the unchanged logical request with its original key.
- 03
Use bounded backoff
Limit attempts, add jitter and stop retrying when the operation has a terminal response.
- 04
Escalate with identifiers
Provide the request ID, environment, endpoint, timestamp and your non-sensitive source reference. Never send the bearer key.