Error Handling

The Flash Americas API uses conventional HTTP response codes to indicate the success or failure of API requests. This guide covers common error scenarios and how to handle them effectively.

HTTP Status Codes

CodeMeaningDescription
200OKRequest succeeded
201CreatedResource created successfully
400Bad RequestInvalid request parameters
401UnauthorizedInvalid or missing API key
403ForbiddenInsufficient permissions
404Not FoundResource doesn't exist
409ConflictResource already exists
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error
503Service UnavailableTemporary service issue

Error Response Format

All API errors return a consistent JSON structure:

Standard error responsejson
{
"success": false,
"error": {
  "code": "ERROR_CODE",
  "message": "Human readable error message",
  "details": {
    "field": "fieldName",
    "value": "rejectedValue"
  }
},
"meta": {
  "requestId": "req_123456789",
  "timestamp": "2025-01-15T10:30:00Z"
}
}

Common Errors

Authentication Errors

Invalid API keyjson
{
"success": false,
"error": {
  "code": "AUTHENTICATION_ERROR",
  "message": "Invalid API key"
}
}

Validation Errors

Invalid addressjson
{
"success": false,
"error": {
  "code": "INVALID_ADDRESS",
  "message": "The destination address could not be validated",
  "details": {
    "field": "destinationAddress.postalCode",
    "suggestions": ["77001-4567", "77002"]
  }
}
}

Rate Limit Errors

Rate limit exceededjson
{
"success": false,
"error": {
  "code": "RATE_LIMIT_ERROR",
  "message": "Rate limit exceeded",
  "details": {
    "limit": 1000,
    "retryAfter": 60
  }
}
}

Error Handling Best Practices

1. Implement Retry Logic

Retry with exponential backoffjavascript
async function apiRequestWithRetry(url, options, maxRetries = 3) {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
  try {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, attempt);
      await sleep(retryAfter * 1000);
      continue;
    }
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    
    return await response.json();
  } catch (error) {
    if (attempt === maxRetries) throw error;
    await sleep(Math.pow(2, attempt) * 1000);
  }
}
}

2. Handle Specific Error Types

Comprehensive error handlingjavascript
function handleApiError(error) {
switch (error.code) {
  case 'AUTHENTICATION_ERROR':
    // Redirect to login or refresh API key
    redirectToLogin();
    break;
    
  case 'RATE_LIMIT_ERROR':
    // Implement backoff strategy
    const retryAfter = error.details?.retryAfter || 60;
    scheduleRetry(retryAfter);
    break;
    
  case 'INVALID_ADDRESS':
    // Show address validation UI
    showAddressCorrection(error.details.suggestions);
    break;
    
  case 'NO_RATES_AVAILABLE':
    // Inform user about service limitations
    showNoRatesMessage();
    break;
    
  default:
    // Log unexpected errors
    console.error('Unexpected API error:', error);
    showGenericErrorMessage();
}
}

Next Steps