Error Handling

The Partner API uses standard HTTP status codes and returns consistent JSON error responses.

Error Response Format

All errors follow this structure:

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

Status Codes

Code	Error	Description
`400`	Bad Request	Invalid request body, missing required fields, or validation failure
`401`	Unauthorized	Missing, invalid, or expired authentication credentials
`403`	Forbidden	Valid credentials but insufficient permissions for this action
`404`	Not Found	The requested resource does not exist
`409`	Conflict	Duplicate request detected (e.g., duplicate idempotency key with different payload)
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	An unexpected error occurred on the server

Validation Errors

For 400 errors caused by request validation, the message field may contain details about which fields failed validation:

{
	"statusCode": 400,
	"message": [
		"products.0.productId must be a UUID",
		"products.0.startAt must be a valid ISO 8601 date",
		"payment.type must be one of: CARD, GOOGLE_PAY, APPLE_PAY, IDEAL, REVOLUT, BANCONTACT"
	],
	"error": "Bad Request"
}

Best Practices

Always check the statusCode field to determine the error category.
For 401 errors, verify your API key, timestamp freshness (within 5 minutes), nonce uniqueness, and signature computation.
For 409 errors on order creation, the original order was already processed. Retrieve it using the idempotency key or external reference.
For 500 errors, retry with exponential backoff. If the error persists, contact support.