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

# Error Codes

> Complete reference of API error codes

## Error Response Format

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "English message",
    "message_es": "Mensaje en español",
    "details": { ... },
    "requestId": "req_abc123"
  }
}
```

## Authentication Errors (401/403)

| Code                            | HTTP | Description                                    |
| ------------------------------- | ---- | ---------------------------------------------- |
| `AUTH_MISSING_API_KEY`          | 401  | No API key provided in X-API-Key header        |
| `AUTH_INVALID_API_KEY`          | 401  | API key is invalid, expired, or revoked        |
| `AUTH_KEY_DISABLED`             | 401  | API key has been disabled                      |
| `AUTH_COUNTRY_NOT_ALLOWED`      | 403  | API key not authorized for destination country |
| `AUTH_IP_NOT_ALLOWED`           | 403  | Request IP not in API key's whitelist          |
| `AUTH_INSUFFICIENT_PERMISSIONS` | 403  | API key lacks required permissions             |

## Validation Errors (400)

### General Validation

| Code                        | Description                          |
| --------------------------- | ------------------------------------ |
| `VALIDATION_FAILED`         | One or more fields failed validation |
| `VALIDATION_REQUIRED_FIELD` | Required field is missing            |
| `VALIDATION_INVALID_FORMAT` | Field format is invalid              |
| `VALIDATION_MAX_LENGTH`     | Field exceeds maximum length         |
| `VALIDATION_MIN_LENGTH`     | Field below minimum length           |
| `VALIDATION_INVALID_VALUE`  | Field value is not in allowed set    |

### Address Validation

| Code                         | Description                             |
| ---------------------------- | --------------------------------------- |
| `VALIDATION_ADDRESS`         | General address validation failure      |
| `VALIDATION_COUNTRY_CODE`    | Invalid ISO 3166-1 alpha-2 country code |
| `VALIDATION_STATE_CODE`      | Invalid state/province code             |
| `VALIDATION_POSTAL_CODE`     | Invalid postal code format              |
| `VALIDATION_POSTAL_MISMATCH` | Postal code doesn't match region        |

### Identity Validation

| Code                     | Description                |
| ------------------------ | -------------------------- |
| `VALIDATION_NATIONAL_ID` | Invalid national ID format |
| `VALIDATION_CEDULA`      | Invalid Ecuadorian Cédula  |
| `VALIDATION_RUC`         | Invalid Ecuadorian RUC     |
| `VALIDATION_RFC`         | Invalid Mexican RFC        |
| `VALIDATION_DNI`         | Invalid Peruvian DNI       |
| `VALIDATION_RUT`         | Invalid Chilean RUT        |

### Contact Validation

| Code                      | Description                             |
| ------------------------- | --------------------------------------- |
| `VALIDATION_PHONE`        | Invalid phone number format             |
| `VALIDATION_EMAIL`        | Invalid email format                    |
| `VALIDATION_EMAIL_DOMAIN` | Suspicious email domain (typo detected) |

### Parcel Validation

| Code                    | Description                                   |
| ----------------------- | --------------------------------------------- |
| `VALIDATION_WEIGHT`     | Weight out of allowed range                   |
| `VALIDATION_DIMENSIONS` | Dimensions out of allowed range               |
| `VALIDATION_VALUE`      | Declared value out of range                   |
| `VALIDATION_CHECKSUM`   | Product checksum doesn't match declared value |

## Order Errors (404/409)

| Code                        | HTTP | Description                           |
| --------------------------- | ---- | ------------------------------------- |
| `PARCEL_NOT_FOUND`          | 404  | Tracking number doesn't exist         |
| `PARCEL_DUPLICATE_TRACKING` | 409  | Tracking number already in use        |
| `PARCEL_ALREADY_VOIDED`     | 409  | Order has already been cancelled      |
| `PARCEL_IN_TRANSIT`         | 409  | Cannot modify order in transit        |
| `PARCEL_DELIVERED`          | 409  | Cannot modify delivered order         |
| `PARCEL_ASSIGNED`           | 409  | Parcel already assigned to a manifest |

## Manifest Errors (400/409)

| Code                         | HTTP | Description                           |
| ---------------------------- | ---- | ------------------------------------- |
| `MANIFEST_NOT_FOUND`         | 404  | Manifest/AWB not found                |
| `MANIFEST_LOCKED`            | 409  | Manifest already submitted and locked |
| `MANIFEST_AWB_DUPLICATE`     | 409  | AWB number already exists             |
| `MANIFEST_VALIDATION_FAILED` | 400  | Country-specific validation failed    |
| `MANIFEST_EMPTY`             | 400  | Manifest has no parcels               |

## Label Errors (404/409)

| Code                      | HTTP | Description                         |
| ------------------------- | ---- | ----------------------------------- |
| `LABEL_NOT_FOUND`         | 404  | Label not found for tracking number |
| `LABEL_NOT_GENERATED`     | 409  | Label not yet generated             |
| `LABEL_GENERATION_FAILED` | 500  | Label generation failed             |

## Rate Limiting (429)

| Code                  | Description                  |
| --------------------- | ---------------------------- |
| `RATE_LIMIT_EXCEEDED` | Request rate limit exceeded  |
| `RATE_LIMIT_DAILY`    | Daily request quota exceeded |

Response includes `retryAfter` field:

```json theme={null}
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "retryAfter": 30
  }
}
```

## Idempotency Errors (409)

| Code                      | Description                               |
| ------------------------- | ----------------------------------------- |
| `IDEMPOTENCY_CONFLICT`    | Same key used with different payload      |
| `IDEMPOTENCY_IN_PROGRESS` | Request with this key is still processing |

## Server Errors (500)

| Code                  | Description                     |
| --------------------- | ------------------------------- |
| `INTERNAL_ERROR`      | Unexpected server error         |
| `SERVICE_UNAVAILABLE` | Service temporarily unavailable |
| `DATABASE_ERROR`      | Database operation failed       |
| `CARRIER_ERROR`       | Carrier API error               |

## Handling Errors

### Retryable Errors

These errors can be retried with exponential backoff:

* `RATE_LIMIT_EXCEEDED`
* `SERVICE_UNAVAILABLE`
* `INTERNAL_ERROR` (after delay)
* `IDEMPOTENCY_IN_PROGRESS` (after short delay)

### Non-Retryable Errors

These errors require code changes or user action:

* `AUTH_*` errors
* `VALIDATION_*` errors
* `*_NOT_FOUND` errors
* `*_DUPLICATE_*` errors
* `*_LOCKED` errors

### Example Error Handler

```javascript theme={null}
function shouldRetry(error) {
  const retryableCodes = [
    'RATE_LIMIT_EXCEEDED',
    'SERVICE_UNAVAILABLE',
    'INTERNAL_ERROR',
    'IDEMPOTENCY_IN_PROGRESS'
  ];
  
  return retryableCodes.includes(error.code);
}
```