Error Codes

Error Response Format

{
  "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:

{
  "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

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

Getting Started

Reference

Error Response Format

Authentication Errors (401/403)

Validation Errors (400)

General Validation

Address Validation

Identity Validation

Contact Validation

Parcel Validation

Order Errors (404/409)

Manifest Errors (400/409)

Label Errors (404/409)

Rate Limiting (429)

Idempotency Errors (409)

Server Errors (500)

Handling Errors

Retryable Errors

Non-Retryable Errors

Example Error Handler

​Error Response Format

​Authentication Errors (401/403)

​Validation Errors (400)

​General Validation

​Address Validation

​Identity Validation

​Contact Validation

​Parcel Validation

​Order Errors (404/409)

​Manifest Errors (400/409)

​Label Errors (404/409)

​Rate Limiting (429)

​Idempotency Errors (409)

​Server Errors (500)

​Handling Errors

​Retryable Errors

​Non-Retryable Errors

​Example Error Handler

Error Response Format

Authentication Errors (401/403)

Validation Errors (400)

General Validation

Address Validation

Identity Validation

Contact Validation

Parcel Validation

Order Errors (404/409)

Manifest Errors (400/409)

Label Errors (404/409)

Rate Limiting (429)

Idempotency Errors (409)

Server Errors (500)

Handling Errors

Retryable Errors

Non-Retryable Errors

Example Error Handler