Error Handling

Learn how to handle errors from API Hub APIs and implement robust error handling in your applications.

Error Response Format

All APIs in API Hub use a consistent error format to make handling errors predictable. When an error occurs, the API will return a non-2xx status code and a JSON response with error details.

{
  "error": {
    "status": 400,
    "code": "invalid_request",
    "message": "The request was invalid",
    "details": "Required parameter 'name' is missing",
    "requestId": "req_1234567890"
  }
}

The error response contains the following fields:

status

The HTTP status code of the error (also included in the HTTP response status)

code

A machine-readable error code

message

A human-readable error message

details

Additional details about the error (optional)

requestId

A unique identifier for the request, useful for troubleshooting with support

Common Error Status Codes

Here are the most common error status codes you might encounter when using our APIs:

Status Code	Name	Description	How to Resolve
401	Unauthorized	The request lacks valid authentication credentials or the API key is invalid.	Check that you're providing a valid API key and that it has the correct permissions.
403	Forbidden	The API key doesn't have permission to perform the requested action.	Verify that your API key has the necessary permissions to access this resource.
429	Too Many Requests	You've exceeded the rate limit for your API key.	Reduce your request rate, implement backoff strategies, or upgrade your plan for higher rate limits.
500	Internal Server Error	An unexpected error occurred on the server.	Contact support with the request ID for assistance.
503	Service Unavailable	The service is temporarily unavailable, possibly due to maintenance or high load.	Implement retry logic with exponential backoff in your application.

Important Note

This documentation covers general authentication and common errors. For API-specific error codes and status messages, refer to the documentation for each individual API.

Best Practices for Error Handling

Always Check Status Codes

Don't assume that API calls will always succeed.
Always check the HTTP status code of the response before processing data.

Implement Retry Logic

For transient errors (such as 429 or 503), implement retry logic with exponential backoff.

async function fetchWithRetry(url, options, maxRetries = 3) {
  let retries = 0;
  
  while (retries < maxRetries) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429 || response.status === 503) {
        // Get retry-after header or use exponential backoff
        const retryAfter = response.headers.get('retry-after') || Math.pow(2, retries) * 1000;
        await new Promise(resolve => setTimeout(resolve, retryAfter));
        retries++;
        continue;
      }
      
      return response;
    } catch (error) {
      if (retries >= maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, retries) * 1000));
      retries++;
    }
  }
}

Log Error Details

For debugging purposes, log error details including the requestId from the error response. This will help you and the support team diagnose issues:

// JavaScript example
try {
  const response = await fetch(url, options);
  if (!response.ok) {
    const errorData = await response.json();
    console.error(`API Error: ${response.status}, Request ID: ${errorData.error.requestId}`, errorData);
    // Handle error appropriately
  }
} catch (error) {
  console.error('Network or parsing error:', error);
}

Provide Meaningful Feedback to Users

Translate API errors into user-friendly messages that help them understand what went wrong and how to fix it.

Need Help With Errors?

If you encounter persistent errors or need help understanding an error response, contact our support team with the request ID.

General Docs