Error Handling

Error Response Format

All API errors return a consistent JSON structure:

{
  "status_code": 400,
  "message": "Bad Request",
  "error": "Detailed error description",
  "errors": ["field: validation message"]  // Optional, for validation errors
}

Field	Type	Description
`status_code`	number	HTTP status code
`message`	string	HTTP status message
`error`	string	Human-readable error description
`errors`	string[]	Array of validation errors (when applicable)

HTTP Status Codes

Success Codes

Code	Description
`200 OK`	Request succeeded
`201 Created`	Resource created successfully
`204 No Content`	Request succeeded with no response body

Client Error Codes

Code	Description	Common Causes
`400 Bad Request`	Invalid request	Validation errors, malformed JSON
`401 Unauthorized`	Authentication failed	Missing or invalid API key
`403 Forbidden`	Access denied	Insufficient permissions
`404 Not Found`	Resource not found	Invalid ID or deleted resource
`409 Conflict`	Resource conflict	Duplicate entry or state conflict
`422 Unprocessable Entity`	Business logic error	Insufficient balance, expired payment
`429 Too Many Requests`	Rate limit exceeded	Slow down requests

Server Error Codes

Code	Description	Action
`500 Internal Server Error`	Server error	Retry with backoff
`502 Bad Gateway`	Upstream error	Retry with backoff
`503 Service Unavailable`	Service down	Check status page

Common Error Scenarios

Validation Errors

When request validation fails, you’ll receive a 400 response with details:

{
  "status_code": 400,
  "message": "Bad Request",
  "error": "Validation failed",
  "errors": [
    "amount: must be a positive number",
    "currency_code: must be one of [USDC]"
  ]
}

Authentication Errors

Missing or invalid API key returns 401:

{
  "status_code": 401,
  "message": "Unauthorized",
  "error": "Invalid or missing API key"
}

Resource Not Found

When a resource doesn’t exist:

{
  "status_code": 404,
  "message": "Not Found",
  "error": "Payment not found"
}

Insufficient Balance

When attempting a payment without sufficient funds:

{
  "status_code": 422,
  "message": "Unprocessable Entity",
  "error": "Insufficient balance. Available: 50.00 USDC, Required: 100.00 USDC"
}

Payment Already Processed

When trying to notify for an already processed payment:

{
  "status_code": 400,
  "message": "Bad Request",
  "error": "Payment has already been processed"
}

Error Handling Best Practices

1. Always Check Status Codes

const response = await fetch('https://api-sandbox.superbank.com/v1/payments', {
  method: 'POST',
  headers: {
    'X-Api-Key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(paymentData),
});

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

  switch (response.status) {
    case 400:
      console.error('Validation error:', error.errors);
      break;
    case 401:
      console.error('Authentication failed - check your API key');
      break;
    case 422:
      console.error('Business error:', error.error);
      break;
    default:
      console.error('Unexpected error:', error);
  }
}

2. Implement Retry Logic

For transient errors (5xx), implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status < 500) {
      return response;
    }

    // Exponential backoff: 1s, 2s, 4s
    const delay = Math.pow(2, attempt) * 1000;
    await new Promise(resolve => setTimeout(resolve, delay));
  }

  throw new Error('Max retries exceeded');
}

3. Handle Rate Limits

If you receive a 429 response, respect the Retry-After header:

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  const delay = retryAfter ? parseInt(retryAfter) * 1000 : 60000;
  await new Promise(resolve => setTimeout(resolve, delay));
  // Retry the request
}

Idempotency

For payment creation, use the idempotency_key field to safely retry requests:

{
  "type": "LIQUIDITY",
  "amount": 100.00,
  "currency_code": "USDC",
  "chain": "SOLANA",
  "destination_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "idempotency_key": "order-12345"
}

If you send the same request with the same idempotency key, you’ll receive the original payment instead of creating a duplicate.

Get Started

Error Response Format

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Common Error Scenarios

Validation Errors

Authentication Errors

Resource Not Found

Insufficient Balance

Payment Already Processed

Error Handling Best Practices

1. Always Check Status Codes

2. Implement Retry Logic

3. Handle Rate Limits

Idempotency

Next Steps

Pagination

Webhooks

Get Started

​Error Response Format

​HTTP Status Codes

​Success Codes

​Client Error Codes

​Server Error Codes

​Common Error Scenarios

​Validation Errors

​Authentication Errors

​Resource Not Found

​Insufficient Balance

​Payment Already Processed

​Error Handling Best Practices

​1. Always Check Status Codes

​2. Implement Retry Logic

​3. Handle Rate Limits

​Idempotency

​Next Steps

Pagination

Webhooks

Error Response Format

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Common Error Scenarios

Validation Errors

Authentication Errors

Resource Not Found

Insufficient Balance

Payment Already Processed

Error Handling Best Practices

1. Always Check Status Codes

2. Implement Retry Logic

3. Handle Rate Limits

Idempotency

Next Steps