Error Handling

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.