Errors & status codes
Partner API errors are JSON objects with a stable code and human-readable message. HTTP status mirrors the failure class.
Error envelope
Example
{ "code": "VALIDATION_FAILED", "message": "Invalid JSON body"}HTTP & code map
| HTTP | code | Meaning |
|---|---|---|
| 401 | UNAUTHORIZED | Missing/invalid Bearer token or revoked key |
| 403 | FORBIDDEN | Scope missing, IP blocked, or production not approved |
| 400 | VALIDATION_FAILED | Bad JSON or field validation |
| 400 | DEVELOPER_PRICE_MISSING | Package has no Developer/API price configured |
| 402 | INSUFFICIENT_FUNDS | Wallet / sandbox balance too low |
| 404 | NOT_FOUND | Unknown product or transaction id |
| 409 | IDEMPOTENCY_CONFLICT | Same key reused with a different request payload |
| 409 | DUPLICATE_EXTERNAL_REFERENCE | externalReference already used for this app + environment |
| 4xx/5xx | Domain codes | Catalog rules, fulfillment failures, etc. |
Transaction status values
| status | Terminal? | Notes |
|---|---|---|
pending | No | Accepted; await fulfillment |
processing | No | In flight with provider / simulator |
completed | Yes | Success — check token for ECG |
failed | Yes | See errorCode + customerMessage |