Errors

Partner and merchant API errors use a consistent JSON envelope.

Error Envelope

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Field Meaning

Field	Type	Description
statusCode	number	HTTP status code returned by the endpoint.
message	string	Human-readable error message.
error	string	Standard HTTP error label, for example Bad Request or Conflict.

Common Status Codes

Code	Meaning
400	Invalid body, invalid path parameter, or missing/invalid required header (for example Idempotency-Key).
401	Missing or invalid authentication headers (X-API-Key, X-Timestamp, or X-Signature).
403	API key is not allowed for the caller IP or the operation is blocked by policy.
404	Requested resource was not found.
409	Idempotency conflict (same key with different payload) or request already in progress for that key.
422	Business rule rejection, such as partner limit checks.
500	Unexpected server error.

Validation Notes

• Validation failures may return message: "Validation failed" when multiple field errors are present.
• Treat message as the primary troubleshooting signal and statusCode as the handling branch.