Error Handling

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message in English",
    "message_es": "Mensaje legible en español",
    "details": { },
    "requestId": "req_abc123xyz"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "details": {
      "errors": [
        {
          "field": "receiver.nationalId",
          "message": "National ID is required for Ecuador shipments"
        },
        {
          "field": "parcelDetails.weightLbs",
          "message": "Weight must be positive"
        }
      ]
    }
  }
}

{
  "success": false,
  "error": {
    "code": "AUTH_INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked"
  }
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please wait before retrying.",
    "retryAfter": 30
  }
}

{
  "success": false,
  "error": {
    "code": "PARCEL_DUPLICATE_TRACKING",
    "message": "A parcel with this tracking number already exists"
  }
}

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again.",
    "requestId": "req_abc123xyz"
  }
}

async function apiCallWithRetry(fn, maxRetries = 3) {
  let lastError;
  
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;
      
      // Don't retry validation or auth errors
      if (error.status === 400 || error.status === 401) {
        throw error;
      }
      
      // Don't retry conflict errors (409) except for rate limits
      if (error.status === 409 && error.code !== 'RATE_LIMIT_EXCEEDED') {
        throw error;
      }
      
      // Calculate delay with exponential backoff
      const delay = error.retryAfter 
        ? error.retryAfter * 1000 
        : Math.min(1000 * Math.pow(2, attempt), 30000);
      
      console.log(`Retry ${attempt + 1}/${maxRetries} after ${delay}ms`);
      await sleep(delay);
    }
  }
  
  throw lastError;
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

curl -H "Accept-Language: es" ...