Error codes
All errors are RFC 9457 problem details (application/problem+json) with a stable code. Extra fields named in the table are returned at the top level of the problem object.
{ "type": "https://agents.snappy.com/docs/errors#address_unverified", "title": "We could not verify this address: …", "status": 422, "code": "address_unverified", "suggestions": [ … ] }| Code | HTTP | Meaning | What the agent should do |
|---|---|---|---|
validation_error | 400 | Request body or query failed validation | Fix the request; details in `issues` |
unauthorized | 401 | Missing, expired or revoked access token | Refresh the token or re-run the OAuth flow |
insufficient_scope | 403 | Token lacks the scope for this operation | Ask the user to re-authorize with the listed scope (they may have chosen read-only) |
user_suspended | 403 | The account is suspended | Tell the user to contact Snappy support |
catalog_not_found | 404 | Product, variant or collection does not exist | Search again; ids may have been recalled |
quote_not_found | 404 | Unknown quote id or not owned by this user | Create a new quote |
checkout_not_found | 404 | Unknown checkout id or not owned by this user | List checkouts |
order_not_found | 404 | Unknown order id or not owned by this user | List orders |
quote_expired | 409 | Quotes are valid for 15 minutes | Create a new quote and show the user the (possibly changed) price |
checkout_not_cancellable | 409 | Only unpaid checkouts can be cancelled | If paid, cancel the order instead |
order_not_cancellable | 409 | Fulfilment already started | Offer the support link from the error |
country_not_supported | 422 | The platform does not ship to that country | Offer the countries in `allowedCountries` |
variant_unavailable_in_country | 422 | Snappy cannot ship this variant there right now | Offer `availableCountries` or another variant |
address_incomplete | 422 | Physical items need address1, city, postalCode | Collect the `missing` fields |
address_unverified | 422 | Snappy could not verify the address | Show `suggestions` from autocomplete and confirm with the user |
address_country_mismatch | 422 | Address country differs from the quoted country | Create a quote for the address country |
phone_invalid | 422 | Phone must be E.164 | Ask for the number with country code |
cart_empty | 400 | No items in the checkout | Create quotes first |
quantity_invalid | 400 | quantity must be 1-10 per line | Split large quantities |
cart_too_large | 422 | More than 20 items in one checkout | Split into two checkouts |
cart_country_mismatch | 422 | Quotes priced for different countries | Re-quote all items for the shipping country |
sms_consent_required | 422 | SMS needs explicit consent | Show `consentText`, get a yes, resend with smsConsent=true |
sms_opted_out | 422 | The number replied STOP | Offer email, or ask the user to text START |
use_cancel_endpoint | 409 | Order is still cancellable | Call cancelOrder instead of a support request |
order_already_refunded | 409 | Nothing left to refund | Explain the refund already happened |
snappy_not_configured | 503 | Operators have not entered the Snappy key yet | Tell the user the store is not open yet |
payments_not_configured | 503 | Operators have not entered Stripe keys yet | Browsing works; purchases are not available yet |
order_total_too_high | 422 | Above the platform cap | Point the user to Snappy support |
otp_rate_limited | 429 | Too many sign-in codes requested | Wait before requesting another code |
catalog_busy | 503 | Snappy rate limit hit | Retry after `Retry-After` seconds |
maintenance | 503 | Checkout is paused by Snappy operations | Show the message and retry later; browsing still works |
catalog_upstream_error | 502 | Snappy API returned an error | Retry once; then apologise and offer to try later |
OAuth errors
The token and registration endpoints use RFC 6749 bodies: { "error": "invalid_grant", "error_description": "…" }.
Snappy Agents · agents.snappy.com · support@snappy.com