Error Handling

Learn how to handle errors from the Caibo API.

Error Response Format

When an error occurs, the API returns a JSON response with details about the error:

error-response.json
{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_too_small",
    "message": "The transfer amount must be at least 1.00 USD",
    "param": "amount",
    "doc_url": "https://docs.caibopay.com/errors/amount_too_small"
  }
}

HTTP Status Codes

CodeDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
422Unprocessable Entity - Valid syntax but semantic errors
429Too Many Requests - Rate limit exceeded
500Internal Server Error

Error Types

invalid_request_error

The request was malformed or contains invalid parameters.

authentication_error

The API key is invalid or missing.

rate_limit_error

You've exceeded the rate limit. Wait and retry.

api_error

Something went wrong on our end. Contact support if this persists.

Handling Errors in Code

error-handling.js
import CaiboPay from '@caibopay/sdk';

const caibo = new CaiboPay({ apiKey: 'sk_test_...' });

try {
  const transfer = await caibo.transfers.create({
    amount: 1000,
    currency: 'USD',
    // ...
  });
} catch (error) {
  if (error.type === 'invalid_request_error') {
    console.log('Invalid request:', error.message);
    console.log('Parameter:', error.param);
  } else if (error.type === 'authentication_error') {
    console.log('Check your API key');
  } else if (error.type === 'rate_limit_error') {
    console.log('Rate limited. Retry after:', error.retryAfter);
  } else {
    console.log('Unexpected error:', error.message);
  }
}

Idempotency

To safely retry requests, include an Idempotency-Key header:

idempotency.js
const transfer = await caibo.transfers.create({
  amount: 1000,
  currency: 'USD',
  // ...
}, {
  idempotencyKey: 'unique-request-id-12345'
});