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.

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.