Logo
Become a Client

Data API – Error Handling

In any integration, it’s important to handle errors gracefully and understand how version changes are managed. This section covers the common API errors and the API version lifecycle.

Common Error Codes

The IDC API uses standard HTTP status codes to indicate success or failure. When an error occurs, the response usually contains a JSON body with an “errors” field explaining the issue. Here are typical error codes and what they mean:

  • 400 Bad Request: The request was not formatted correctly or missing required data. This could be a typo in the URL, invalid JSON in the body, or an incorrect parameter. Check your request and try again.
  • 401 Unauthorized: Your API key is missing, invalid, or expired. Make sure you included the x-api-key header and that the key is correct. If your key has expired, contact IDC for a new one.
  • 403 Forbidden: You are authenticated but not allowed to access this resource. This might occur if you try to access a product or export that is not in your subscription.
  • 404 Not Found: The endpoint or resource doesn’t exist. For example, using a wrong URL path, or an exportId/fileId that doesn’t exist (possibly a typo or an ID from a different environment). It can also happen if you use an incorrect Version ID or one that has been retired.
  • 429 Too Many Requests: You have hit a rate limit. The API throttling limits might have been exceeded (see above in Advanced Integration: e.g., >10 export registrations in a minute or >40 requests/minute overall). If you see this, implement backoff and retry after a delay. The error message “Too Many Requests” indicates you should slow down.
  • 50x Server Error: A 500-series code (500, 502, 503, etc.) indicates a problem on IDC’s side. This could be temporary (e.g., a service is down or an unexpected exception occurred). If you get a server error, you might retry after some seconds. If it persists, you may need to contact IDC support to investigate.

JSON Error Response

When an error response has a JSON body, it looks like:

{
  "errors": [
    "There has been an XYZ error."
  ]
}

This array may contain one or multiple messages providing detail. Always check this message as it can clarify what went wrong (for example, it might say a certain field is unrecognized in your query).