Get started

When integrating with Shell APIs, proper error handling ensures reliability and a smooth user experience. Below are the recommended practices:

Standard HTTP Status Codes

• 2xx – Success
• 4xx – Client errors (e.g., invalid input)
• 5xx – Server errors (retryable)

Error Response Structure

Typical error response:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "FAILED",
  "Errors": [
     {
        "Code": "E0001",
        "Detail": "Invalid parameter value for AddressLine1",
        "Title": "Validation Error",
        "AdditionalInfo": {
          "addressLine1": "John Marks street ?"
        }
     }
  ]
}

Error Code Reference

Retry Logic

• Retry only on 5xx errors or network timeouts
• Use exponential backoff (e.g., 1s, 2s, 4s)
• Do not retry on 4xx errors; fix the request instead

Rate Limiting

• If you receive 429 Too Many Requests, respect the Retry-After header before retrying

Logging & Monitoring

• Always log RequestId for troubleshooting
• Mask sensitive data (tokens, credentials) in logs

Request ID Guidelines

• Use a requestId in UUID v4 format (e.g., 123e4567-e89b-12d3-a456-426614174000) for every request
• Helps with log correlation, debugging, and tracing across services
• Generate once at the entry point and propagate downstream

Example Error Scenarios

• Invalid Payload: Ensure JSON structure matches API spec
• Authentication Failure: Refresh token and retry
• Quota Exceeded: Implement usage monitoring and alerts

Additional Information

• Additional Info: Some error scenarios include additional information in the error payload under the AdditionalInfo section. Look for this section to investigate more details about the error.