Errors

Errors can happen because of validation, authentication, account state, payment failures, rate limits, or upstream service issues.

Response Format

Error responses usually include a success flag and a message, or a framework-level detail field for authentication and permission failures.

{
  "success": false,
  "message": "Invalid request payload"
}

HTTP Status Codes

Status	Meaning	Action
400	Bad request. Required fields are missing or invalid.	Fix request payload.
401	Not authenticated. API key is missing or invalid.	Check the Authorization header.
403	Not authorized. Account or key is not allowed to perform the action.	Check account/key permissions.
404	Resource not found.	Check IDs, URLs, or transaction references.
429	Too many requests.	Retry later with backoff.
500	Server error or upstream failure.	Retry safely or contact support if persistent.

Recommended handling

• Show customer-safe messages in the frontend.
• Log full technical details on your backend.
• Use idempotency in fulfillment and settlement systems.
• Confirm final payment status through webhooks or transaction lookup.