Error Handling
Overview
Our API uses conventional HTTP response codes to indicate the outcome of an API request. Codes in the 2xx range indicate success, the 4xx category indicate an error that failed given the information provided (such as a required parameter being missing), and 5xx codes imply there's an error with our servers (which will rarely happen).
API error messages are returned in JSON format and include precise HTTP status codes in the header. While the text for an error message and type may change, the code ID and its indication will stay the same.
At Tomorrow.io, we don't fail often - but when we do, we try to fail gracefully. That's why our API makes an incredible effort to always return the best data available under any condition that surfaced while doing so. We call those "soft errors" and, much like "hard errors" they will be provided as part of the response.
Error Response Format
All error responses follow a consistent JSON structure with type and message fields:
Hard Errors
{
"type": "Not Found",
"message": "The insight associated with the request could not be found: 38f68803c2d3eb8d04ba95f2ea3"
}Soft Errors
{
"type": "Invalid Body Parameters",
"message": "The entries provided as body parameters were not valid for the request."
}4xx Range
400 BAD REQUEST
To read more on usage limits (rate-limiting) see the Usage Limiting section.
| Code | Type | Description |
|---|---|---|
| 400001 | Invalid Body Parameters | The entries provided as body parameters were not valid for the request. |
| 400002 | Invalid Query Parameters | The entries provided as query parameters were not valid for the request. |
| 400003 | Missing Required Body Parameters | The request is missing some required body parameters. |
| 400004 | Missing Required Query Parameters | The request is missing the required query parameters. |
| 400005 | Rule Violation | The request violated business logic requirement. |
| 400006 | Missing Required Header Parameters | The request is missing some required header parameters. |
| 400007 | Invalid Path Parameters | The entries provided as path parameters were not valid for the request. |
401 UNAUTHORIZED
| Code | Type | Description |
|---|---|---|
| 401001 | Invalid Key | The method requires authentication, but it was not presented or is invalid. |
402 PAYMENT REQUIRED
| Code | Type | Description |
|---|---|---|
| 402001 | Insufficient Tokens | Adding additional tokens is required. |
403 FORBIDDEN
| Code | Type | Description |
|---|---|---|
| 403001 | Access Denied | The authentication token in use is restricted and cannot access the requested resource. |
| 403002 | Account Limit | The plan limit for a resource has been reached. |
| 403003 | Forbidden Action | The plan is restricted and cannot perform this action. |
404 NOT FOUND
| Code | Type | Description |
|---|---|---|
| 404001 | Not Found | A resource ID was not found. |
5xx Range
500 INTERNAL SERVER ERROR
| Code | Type | Description |
|---|---|---|
| 500001 | Unknown | Possibly a temporary issue due to downtime. Wait and retry the operation. |
| 503001 | Unavailable | Service is currently unavailable, please wait for a while and retry the operation. Supporting header: Retry-After |
Request ID
Each API request has an associated request identifier. You can find this value in the response headers, under X-Correlation-ID.
If you ever need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.
Pro Tip: Always include the X-Correlation-ID when reporting issues or asking for support.
This unique identifier helps our support team quickly locate and troubleshoot your specific API request.
Example Response Headers
HTTP/1.1 400 Bad Request
Content-Type: application/json
X-Correlation-ID: 38f68803-c2d3-4eb8-8d04-ba95f2ea3c7a
Date: Wed, 15 Nov 2023 10:30:00 GMTNeed Help?
If you're experiencing issues that aren't covered in this error handling guide, or need assistance troubleshooting a specific error, our support team is here to help.