Errors and retries
Retry based on operation safety and error meaning, not simply because a response is non-200.
Response model
Successful responses normally include status, message, and data. v2 domain errors additionally include a stable code. Older v1 routes may return only an error string.
HTTP status
| Status | Meaning |
|---|---|
| 200 | Request handled. Inspect data; empty list pages may still use 200. |
| 400 | Invalid input, location, quote, sort field, or customer data. |
| 402 | Insufficient wallet funds. |
| 403 | Missing/invalid key, wrong key type, low service balance, or unavailable product. |
| 404 | Requested product or resource not found. |
| 409 | Quote expired, consumed, or product state changed. |
| 500/503 | Unexpected or temporarily unavailable service. |
Structured codes
ADDRESS_UPGRADE_REQUIREDSend a version 2 address.
DELIVERY_FEE_NOT_FOUNDAsk the customer to choose a supported location.
QUOTE_EXPIREDCreate a fresh quote.
QUOTE_ALREADY_USEDReconcile the existing order.
IDEMPOTENCY_KEY_REQUIREDSupply 8–200 characters.
INSUFFICIENT_FUNDSTop up the wallet matching the key environment.
Retry policy
Retry GET requests with exponential backoff and jitter. Retry quote creation after transient 5xx errors. Retry order creation only with the same idempotency key. Do not retry input, authentication, insufficient-fund, or product-unavailable errors automatically.
Logging
Log endpoint, HTTP status, structured code, your correlation ID, idempotency key hash, and response time. Never log API keys, full customer addresses, phone numbers, wallet credentials, or unredacted request bodies.