> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atlaspay.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

Atlas uses conventional HTTP response codes and returns detailed error information.

## HTTP Status Codes

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

## Error Response Format

```json theme={null}
{
  "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

| Type                    | Description                     |
| ----------------------- | ------------------------------- |
| `api_error`             | Internal server errors (500)    |
| `authentication_error`  | Invalid API key (401)           |
| `card_error`            | Card was declined (402)         |
| `idempotency_error`     | Idempotency key conflict (409)  |
| `invalid_request_error` | Invalid parameters (400)        |
| `rate_limit_error`      | Too many requests (429)         |
| `validation_error`      | Request validation failed (400) |

## Common Error Codes

### Card Errors

| Code                 | Description                        |
| -------------------- | ---------------------------------- |
| `card_declined`      | The card was declined              |
| `insufficient_funds` | The card has insufficient funds    |
| `expired_card`       | The card has expired               |
| `incorrect_cvc`      | The CVC code is incorrect          |
| `processing_error`   | An error occurred while processing |
| `lost_card`          | The card was reported lost         |
| `stolen_card`        | The card was reported stolen       |

### Validation Errors

| Code                     | Description                       |
| ------------------------ | --------------------------------- |
| `invalid_amount`         | Amount must be a positive integer |
| `invalid_currency`       | Currency code is not supported    |
| `missing_required_param` | A required parameter is missing   |
| `invalid_expiry`         | Card expiry date is invalid       |

## Handling Errors

```javascript theme={null}
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.