Skip to main content

Error Codes Reference

Complete reference for all error codes returned by the Courimax API.

Error Response Format​

All errors follow a standard format:

{
  "statusCode": 400,
  "message": "Error description",
  "error": "Bad Request"
}

Some errors include additional details:

{
  "statusCode": 400,
  "message": [
    "externalRef is required",
    "pickupAddress is required"
  ],
  "error": "Bad Request"
}

HTTP Status Codes​

400 Bad Request​

The request was invalid or cannot be processed.

Common Causes:

  • Missing required fields
  • Invalid field format
  • Validation errors

Example:

{
  "statusCode": 400,
  "message": [
    "externalRef (partner order ID) is required",
    "dropoffLat/dropoffLng required unless geocodeOnIngest is true"
  ],
  "error": "Bad Request"
}

Resolution:

  • Check all required fields are present
  • Verify field formats (dates, coordinates, etc.)
  • Review validation error messages

401 Unauthorized​

Authentication credentials are missing or invalid.

Common Causes:

  • Missing X-API-Key header
  • Invalid API key
  • Expired API key

Example:

{
  "statusCode": 401,
  "message": "Missing X-API-Key header",
  "error": "Unauthorized"
}

Resolution:

  • Include X-API-Key header with valid API key
  • Verify API key is active
  • Check API key matches the integration platform

403 Forbidden​

The API key is valid but doesn't have permission for this operation.

Common Causes:

  • API key doesn't match integration platform
  • Insufficient permissions

Example:

{
  "statusCode": 403,
  "message": "API key does not match Yango integration",
  "error": "Forbidden"
}

Resolution:

  • Use the correct API key for the integration platform
  • Contact support if permissions need to be updated

404 Not Found​

The requested resource doesn't exist.

Common Causes:

  • Order not found
  • Invalid external reference
  • Resource belongs to different organization

Example:

{
  "statusCode": 404,
  "message": "Order not found",
  "error": "Not Found"
}

Resolution:

  • Verify the external reference exists
  • Check you're using the correct API key
  • Ensure resource belongs to your organization

409 Conflict​

The request conflicts with the current state of the resource.

Common Causes:

  • Duplicate external reference
  • Invalid state transition
  • Resource already exists

Example:

{
  "statusCode": 409,
  "message": "Order with externalRef YANGO-ORDER-123 already exists",
  "error": "Conflict"
}

Resolution:

  • Use idempotency keys for retries
  • Check for duplicate requests
  • Verify resource state before operation

422 Unprocessable Entity​

The request is well-formed but contains semantic errors.

Common Causes:

  • Zod validation failures
  • Business logic violations
  • Invalid combinations of fields

Example:

{
  "statusCode": 422,
  "message": "Cannot pick_up from status pending",
  "error": "Unprocessable Entity"
}

Resolution:

  • Review validation error messages
  • Check business logic requirements
  • Verify field combinations are valid

429 Too Many Requests​

Rate limit exceeded.

Common Causes:

  • Too many requests in time window
  • Exceeded API quota

Example:

{
  "statusCode": 429,
  "message": "Too many requests, please try again later",
  "error": "Too Many Requests"
}

Resolution:

  • Implement exponential backoff
  • Reduce request frequency
  • Contact support to increase limits

500 Internal Server Error​

An unexpected error occurred on the server.

Common Causes:

  • Server-side bug
  • Database error
  • External service failure

Example:

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

Resolution:

  • Retry the request
  • Contact support if error persists
  • Check status page for service issues

502 Bad Gateway​

The server received an invalid response from an upstream service.

Common Causes:

  • External service failure
  • Network issues

Example:

{
  "statusCode": 502,
  "message": "Bad gateway",
  "error": "Bad Gateway"
}

Resolution:

  • Retry the request
  • Check status page for service issues

503 Service Unavailable​

The server is temporarily unavailable.

Common Causes:

  • Server maintenance
  • Server overload

Example:

{
  "statusCode": 503,
  "message": "Service unavailable",
  "error": "Service Unavailable"
}

Resolution:

  • Retry the request after a delay
  • Check status page for maintenance windows

Validation Errors​

Field Validation​

When fields fail validation, the message field contains an array of errors:

{
  "statusCode": 400,
  "message": [
    "externalRef must be a string",
    "pickupLat must be a number",
    "dropoffLat must be a number"
  ],
  "error": "Bad Request"
}

Schema Validation​

For complex validation errors:

{
  "statusCode": 422,
  "message": "Validation failed",
  "errors": [
    {
      "field": "dropoffLat",
      "message": "dropoffLat/dropoffLng required unless geocodeOnIngest is true"
    }
  ],
  "error": "Unprocessable Entity"
}

State Machine Errors​

Invalid State Transitions​

When attempting an invalid state transition:

{
  "statusCode": 409,
  "message": "Cannot pick_up from status pending",
  "currentStatus": "pending",
  "allowedTransitions": ["dispatch", "assign", "cancel"],
  "error": "Conflict"
}

Resolution:

  • Check current order status
  • Only perform allowed transitions
  • Review order state machine

Rate Limiting​

Rate Limit Headers​

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1629388800
HeaderDescription
X-RateLimit-LimitMaximum requests per window
X-RateLimit-RemainingRemaining requests in window
X-RateLimit-ResetUnix timestamp when window resets

Rate Limit Windows​

Endpoint CategoryLimitWindow
Order creation1001 minute
Order queries5001 minute
Delivery windows2001 minute
Provisioning601 hour

Error Handling Best Practices​

Retry Logic​

Implement retry logic for transient errors:

async function requestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        // Rate limited, wait and retry
        const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
        await sleep(retryAfter * 1000);
        continue;
      }
      
      if (response.status >= 500) {
        // Server error, retry
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

Error Logging​

Log all errors for debugging:

try {
  const response = await fetch(url, options);
  
  if (!response.ok) {
    const error = await response.json();
    logger.error('API request failed', {
      status: response.status,
      error: error.message,
      url: url,
      method: options.method
    });
    throw new Error(error.message);
  }
  
  return await response.json();
} catch (error) {
  logger.error('Request error', error);
  throw error;
}

User-Friendly Messages​

Convert API errors to user-friendly messages:

function getUserFriendlyError(apiError) {
  const errorMap = {
    400: 'Invalid request. Please check your input.',
    401: 'Authentication failed. Please check your API key.',
    403: 'Permission denied. Please contact support.',
    404: 'Resource not found. Please verify the reference.',
    409: 'Conflict detected. Please try again.',
    429: 'Too many requests. Please wait a moment.',
    500: 'Server error. Please try again later.'
  };
  
  return errorMap[apiError.statusCode] || 'An error occurred. Please try again.';
}

Troubleshooting​

Common Issues​

Issue: 401 Unauthorized

  • Verify API key is correct
  • Check API key is active
  • Ensure API key matches platform

Issue: 404 Not Found

  • Verify external reference exists
  • Check you're using correct API key
  • Ensure resource belongs to your organization

Issue: 409 Conflict

  • Check for duplicate requests
  • Use idempotency keys
  • Verify resource state

Issue: 429 Too Many Requests

  • Implement exponential backoff
  • Reduce request frequency
  • Contact support to increase limits

Support​

If you encounter persistent errors:

Next Steps​