API Error
An API Error occurs when a client request to an Application Programming Interface fails to complete successfully, typically returning a non-2xx HTTP status code. Errors are categorized by their origin (client vs. server) and severity, guiding the appropriate retry or correction strategy.
Classification
- Client Errors (4xx): Issues originating from the requestor.
400 Bad Request: The server cannot process the request due to malformed syntax or invalid arguments.401 Unauthorized: Missing or invalid authentication credentials.403 Forbidden: Valid credentials but insufficient permissions.404 Not Found: The requested resource does not exist.429 Too Many Requests: Rate limit exceeded.
- Server Errors (5xx): Issues originating from the service provider.
500 Internal Server Error: Generic server failure.502 Bad Gateway: Invalid response from upstream server.503 Service Unavailable: Server temporarily overloaded or down for maintenance.
Handling Strategies
- Idempotency: Ensure safe retries for non-idempotent methods (e.g.,
POST) using unique request IDs. - Exponential Backoff: Implement delay intervals between retries to avoid overwhelming the server during transient failures.
- Logging & Monitoring: Capture error codes, timestamps, and request payloads for debugging.
- User Feedback: Translate technical errors into actionable user messages.
Related Concepts
- HTTP Status Codes
- Retry Logic
- API Rate Limiting
- JSON Schema Validation