Error Handling: Snappy API Error Codes & Recovery

​

The Error Object

{
  "path": "recipients[0].email",
  "errorCode": "INVALID_REQUEST",
  "message": "Invalid email format."
}

{
  "status": 401,
  "errorCode": "UNAUTHORIZED",
  "message": "Authorization key is invalid."
}

​

V3 error code anatomy

​

HTTP Status Codes

​

400 – Bad Request

• Verify your request body matches the expected schema.
• Ensure all required fields are present (e.g. variantId, recipient.email, idempotencyKey).
• Check that field values are the correct type (e.g. strings vs. integers).
• Inspect path in the response body - it points to the specific field that failed validation.

​

401 – Unauthorized

• Missing header. Ensure you are passing the X-Api-Key header on every request.
• Invalid key. Double-check that the key hasn’t been mistyped or deleted from the Dashboard.
• Expired key. Check whether the key has reached its expiration date and rotate it if needed. See Authentication & Security.

​

403 – Forbidden

• Wrong scope. Check that your API key was created with the correct scope for this action (e.g. orders:create to place an order, products:read to read the catalog). See Authentication & Security.
• Wrong environment. Make sure you are not using a Testing API key against a Production resource or vice versa. See Before You Begin.
• Insufficient masking scope. Reading PII fields requires :read:unmasked rather than :read:masked. See PII Masking.

​

404 – Not Found

• Double-check the ID in your request path - copy it directly from a previous API response to avoid typos.
• Verify the resource was successfully created before attempting to retrieve or update it.
• If you’re scoping with Snappy-Account-Id, verify the resource belongs to that account.

​

422 – Unprocessable Entity

• Read the errorCode and message to understand the specific rule that was violated.
• Common 422 scenarios on V3:
  • Order already in transit - POST /v3/orders/{orderId}/cancel returns 422 once the fulfillment partner has picked up the shipment.
  • Variant not shippable to country - POST /v3/orders returns 422 if the shipping address country is outside the variant’s supported locations.
  • Insufficient billing balance - POST /v3/orders returns 422 when the Billing Method has insufficient funds.
  • Idempotency conflict - replaying an idempotencyKey with a different request body returns 422. Use the same key only with identical bodies.
• Re-issue the request once the underlying state changes (e.g., refunded balance, address updated, order cancelled in time).

​

429 – Too Many Requests

• Pause your requests immediately.
• Respect the Retry-After response header - it tells you how long to wait before retrying.
• Implement an exponential backoff strategy - wait a short period before retrying, and increase the wait time with each subsequent retry.
• Review your request frequency against the published Rate Limits.

​

500 – Internal Server Error

• Check the Snappy Status Page to see if there is an ongoing incident.
• Retry once with a short delay - many 500s are transient.
• If no incident is reported and the issue persists, contact support with:
  • Request URL and method
  • The errorCode returned in the response body
  • A timestamp of when the error occurred
  • The idempotencyKey you used (for writes), so support can correlate without risking a duplicate

​

502 – Bad Gateway

• Retry with exponential backoff. For writes, only retry if you supplied an idempotencyKey - otherwise you risk duplicate side effects.

​

503 – Service Unavailable

• Retry with exponential backoff. Respect the Retry-After header if present.
• If the issue persists across several minutes, check the Snappy Status Page.

​

504 – Gateway Timeout

• Retry with a short delay; most 504s are transient.
• For writes, only retry if you supplied an idempotencyKey (the original request may have actually succeeded before the timeout - the idempotency key lets you safely re-issue without risking a duplicate).
• If a specific endpoint times out consistently, contact support with the request details.

​

Retry & Idempotency

​

Idempotency keys make retries safe

• Generate one stable key per logical operation - e.g., user-{userId}-order-{cartId}. Reuse it on every retry of that operation.
• Never generate a fresh random key on each retry - that defeats the protection and will result in duplicates.
• Replaying with a different body returns 422 (idempotency conflict). Either reuse the original body or pick a new key.
• See Duplicate Detection for the full reference.

​

Exponential backoff

1. First retry: wait ~1 second.
2. Each subsequent retry: double the wait, with random jitter.
3. Cap at ~60 seconds between retries.
4. Give up after 5–7 attempts unless the operation is critical and idempotent. Always respect a Retry-After header if the response includes one - it overrides your local backoff calculation.