API Error Catalog – Your Complete Reference Guide
When working with APIs, encountering errors is inevitable. The challenge isn't avoiding errors—it's understanding them quickly and resolving issues efficiently. The API Error Message Catalog by ToolfolioHub is a searchable reference guide that helps developers quickly identify, understand, and resolve common API errors across REST, GraphQL, and HTTP protocols.
This catalog includes error codes, example JSON responses, explanations, and practical context for each error type. Whether you're debugging a 401 authentication issue, understanding a GraphQL validation error, or troubleshooting a rate limit problem, this tool provides instant clarity.
What is an API Error?
API errors are responses from servers that indicate something went wrong with a request. Unlike successful responses (which typically return data), error responses contain information about what failed and why. Understanding error formats helps developers:
- Debug integration issues faster.
- Implement proper error handling in applications.
- Provide better error messages to end users.
- Document API behavior for team members.
Key Features & Benefits
1. Comprehensive Error Coverage
The catalog includes errors from multiple API types:
- REST API Errors: Standard HTTP status codes (400, 401, 403, 404, 422, 429, 500).
- GraphQL Errors: Validation errors, authentication errors, field resolution errors.
- HTTP Errors: Gateway errors, service unavailable, and server errors.
2. Searchable Interface
Quickly find errors by searching for:
- Error codes (e.g., "404", "UNAUTHORIZED").
- Error names (e.g., "not found", "validation").
- Descriptions or explanations.
3. Filter by Type
Filter errors by API type (REST, GraphQL, HTTP) to narrow down results and focus on relevant errors for your use case.
4. Example JSON Responses
Each error entry includes a complete example JSON response showing the exact format you might receive from an API. This helps you:
- Understand the error structure.
- Implement error parsing in your code.
- Test error handling logic.
Common Error Types Explained
REST API Errors
404 Not Found: The requested resource doesn't exist. Common causes include incorrect URLs, deleted resources, or typos in endpoint paths.
401 Unauthorized: Authentication is required or the provided credentials are invalid. Check your API key, token, or authentication headers.
403 Forbidden: You're authenticated but don't have permission. The request is valid but access is denied—check user roles and permissions.
400 Bad Request: The request format is invalid. Check request body, parameters, and data types.
422 Validation Error: The request format is valid, but data validation failed. Review validation rules and ensure all required fields meet criteria.
429 Too Many Requests: Rate limit exceeded. Wait before retrying or implement exponential backoff.
500 Internal Server Error: Server-side error. Usually indicates a bug on the server—report to API provider if it persists.
GraphQL Errors
GraphQL Validation Error: The query violates schema rules. Check field names, types, and required arguments.
GraphQL Authentication Error: The operation requires authentication. Include valid authentication headers.
GraphQL Field Error: A specific field failed to resolve. Other fields in the query may still succeed—check the error path.
How to Use the Error Catalog
- Search or Browse: Use the search bar to find specific errors, or browse all errors using filter buttons.
- Filter by Type: Click "REST", "GraphQL", or "HTTP" to filter errors by API type.
- Review Error Details: Each error shows:
- Error name and code.
- Brief description.
- Example JSON response.
- Detailed explanation.
- Use Examples: Copy example JSON responses to test error handling in your application.
Typical Use-Cases & Audience
Frontend Developers
Use this catalog to:
- Implement proper error handling in API calls.
- Display user-friendly error messages based on API responses.
- Debug integration issues with backend APIs.
Backend Developers
Use this catalog to:
- Design consistent error response formats.
- Document API error behavior.
- Ensure error responses follow industry standards.
FAQs
What's the difference between 401 and 403?
401 Unauthorized: You're not authenticated (missing or invalid credentials). Log in first.
403 Forbidden: You're authenticated but don't have permission. Your credentials are valid, but your account lacks required permissions.
How should I handle rate limit errors?
When you receive a 429 error:
- Check the `Retry-After` header (if present) to know when to retry.
- Implement exponential backoff—wait progressively longer between retries.
- Reduce request frequency or use batch endpoints if available.
Conclusion
The API Error Message Catalog is an essential reference tool for any developer working with APIs. By providing searchable, categorized error information with real examples, it accelerates debugging and helps you build better error handling into your applications.