Our API uses conventional HTTP response codes to indicate the outcome of an API request. Codes in the 2xx range indicate success, 4xx category indicates errors in the provided information (such as missing or misused parameters or access restrictions) and 5xx codes imply there's an error with our servers (which will rarely happen).
API error messages are returned in JSON format and machine-parsable HTTP status 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 and note any warnings that surfaced while doing so. We call these "soft errors" and, much like "hard errors" they will be provided as part of the response.
{
"code": 404001,
"type": "Not Found",
"message": "The insight associated with the request could not be found: 38f689d83c264eb0b084ba095f2ea332."
}
{
"warnings": [
{
"code": 246001,
"type": "Time Bounded Field",
"message": "The following field is not supported for a time range: hailBinary.",
"meta": {
"field": "hailBinary",
"from": "0h",
"to": "+48h"
}
}
]
}
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 some 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.