Errors

Handle API errors with clear retry and reconciliation rules.

At a glance

Partner API errors use normalized backend responses. Treat authorization, validation, idempotency conflict, and rate-limit errors differently in your client.

Error Catalog

Status	Meaning	Client action
400	Validation failure, unsupported service type, expired quote, or invalid saved card.	Fix the request.
401	Missing, invalid, revoked, or inactive API key.	Rotate or correct credentials.
403	API key lacks required capability or organization payment setting.	Check partner configuration.
404	Resource does not exist in the authenticated partner organization.	Check ID and ownership.
409	Idempotency conflict, already-paid resource, or duplicate in-flight payment.	Reconcile before retrying.
429	Rate limit or abuse guard.	Retry with backoff.

Retry policy

Retry transient 5xx, 429, network timeouts, and pending_verification with jittered backoff.
Do not blindly retry validation or authorization failures.
Reuse the same idempotency key only for the same mutation request body.
Check payment status before creating a second payment attempt.