Skip to main content

​
Error Response Format

API errors are returned in the following format. 
{
  "error": {
    "type": "invalid_request_error",
    "code": "VALIDATION_ERROR",
    "message": "Error description",
    "request_id": "req_abc123xyz789"
  }
}
​
type
string
Error type (authentication_error, invalid_request_error, payment_error, api_error)
​
code
string
Error code (see below)
​
message
string
Error description
​
request_id
string
Request ID (use when contacting support)
​
param
string
Parameter that caused the error (for validation errors)
​
details
array
Detailed error information (for validation errors)

​
Authentication Errors

CodeHTTP StatusDescription
UNAUTHORIZED401Authorization header is invalid or missing
FORBIDDEN403Merchant account is deactivated

​
Validation Errors

CodeHTTP StatusDescription
VALIDATION_ERROR400Invalid request parameters. Details are in the details field
INVALID_AMOUNT400Invalid amount
AMOUNT_BELOW_MINIMUM400Amount is below minimum
AMOUNT_ABOVE_MAXIMUM400Amount exceeds maximum
UNSUPPORTED_CURRENCY400Unsupported currency

​
Payment Errors

CodeHTTP StatusDescription
PAYMENT_FAILED400Payment processing failed
INVALID_STATUS400Operation cannot be performed in current status
INVALID_STATE400Invalid transaction state

​
Refund Errors

CodeHTTP StatusDescription
INVALID_AMOUNT400Refund amount exceeds payment amount
INVALID_STATUS400Not in refundable status (only completed can be refunded)

​
Resource Errors

CodeHTTP StatusDescription
NOT_FOUND404Specified resource not found
FLOW_NOT_FOUND404Payment flow not found
NO_DEFAULT_FLOW404Default payment flow not configured
FLOW_NOT_ACTIVE400Payment flow is disabled
CONNECTOR_CONFIG_NOT_FOUND404Connector configuration not found
CONNECTOR_CONFIG_DISABLED400Connector is disabled

​
Idempotency Errors

CodeHTTP StatusDescription
IDEMPOTENCY_KEY_MISMATCH400Different request sent with same idempotency key
IDEMPOTENCY_KEY_IN_USE409Idempotency key is currently being processed

​
System Errors

CodeHTTP StatusDescription
INTERNAL_ERROR500Internal error occurred. Please contact support

​
Error Handling Best Practices

1

Check HTTP Status Code

  • 4xx: Client error (request needs modification)
  • 5xx: Server error (retriable)
2

Branch Logic by Error Code

Use error.code to implement error-type-specific handling
3

Retry Strategy

For 5xx errors or IDEMPOTENCY_KEY_IN_USE, retry with exponential backoff

​
Sample Code

Node.js
async function createPayment(data) {
  const response = await fetch('https://api.sandbox.zafapay.com/v1/payments', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json',
      'X-Idempotency-Key': generateIdempotencyKey()
    },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    const { error } = await response.json();

    // Log request_id for support inquiries
    console.error(`API Error [${error.request_id}]:`, error.code, error.message);

    switch (error.type) {
      case 'authentication_error':
        // Token refresh required
        throw new AuthError(error.message);

      case 'invalid_request_error':
        // Check request parameters
        if (error.details) {
          console.error('Validation errors:', error.details);
        }
        throw new ValidationError(error.message);

      case 'payment_error':
        // Payment failed (try another payment method)
        throw new PaymentError(error.message);

      case 'api_error':
        // Retriable
        throw new RetryableError(error.message);

      default:
        throw new Error(error.message);
    }
  }

  return response.json();
}