Skip to main content
Atlas uses conventional HTTP response codes and returns detailed error information.

HTTP Status Codes

CodeDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
402Payment Required - Card was declined
404Not Found - Resource doesn’t exist
409Conflict - Idempotency key conflict
429Too Many Requests - Rate limit exceeded
500Internal Server Error

Error Response Format

{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "Your card was declined",
    "decline_code": "insufficient_funds",
    "param": null,
    "request_id": "req_1a2b3c_abc123",
    "doc_url": "https://docs.atlas.co/errors/card_declined"
  }
}

Error Types

TypeDescription
api_errorInternal server errors (500)
authentication_errorInvalid API key (401)
card_errorCard was declined (402)
idempotency_errorIdempotency key conflict (409)
invalid_request_errorInvalid parameters (400)
rate_limit_errorToo many requests (429)
validation_errorRequest validation failed (400)

Common Error Codes

Card Errors

CodeDescription
card_declinedThe card was declined
insufficient_fundsThe card has insufficient funds
expired_cardThe card has expired
incorrect_cvcThe CVC code is incorrect
processing_errorAn error occurred while processing
lost_cardThe card was reported lost
stolen_cardThe card was reported stolen

Validation Errors

CodeDescription
invalid_amountAmount must be a positive integer
invalid_currencyCurrency code is not supported
missing_required_paramA required parameter is missing
invalid_expiryCard expiry date is invalid

Handling Errors

try {
  const session = await atlas.sessions.create({
    amount: 4990,
    currency: 'USD'
  });
} catch (error) {
  switch (error.type) {
    case 'card_error':
      // Show decline message to customer
      console.log(error.message);
      break;
    case 'validation_error':
      // Fix the request parameters
      console.log(`Invalid param: ${error.param}`);
      break;
    case 'authentication_error':
      // Check your API key
      console.log('Invalid API key');
      break;
    default:
      // Something else went wrong
      console.log('Unexpected error:', error.message);
  }
}

Request IDs

Every API response includes a request_id in the error object and X-Request-Id header. Include this when contacting support for faster debugging.