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.

CodeTypeDescription
400001Invalid Body ParametersThe entries provided as body parameters were not valid for the request.
400002Invalid Query ParametersThe entries provided as query parameters were not valid for the request.
400003Missing Required Body ParametersThe request is missing some required body parameters.
400004Missing Required Query ParametersThe request is missing the required query parameters.
400005Rule ViolationThe request violated some logic requirement.
400006Missing Required Header ParametersThe request is missing some required header parameters.
400007Invalid Path ParametersThe entries provided as path parameters were not valid for the request.

401 UNAUTHORIZED:

CodeTypeDescription
401001Invalid KeyThe method requires authentication, but it was not presented or is invalid.

402 PAYMENT REQUIRED:

CodeTypeDescription
402001Insufficient TokensAdding additional tokens is required

403 FORBIDDEN:

CodeTypeDescription
403001Access DeniedThe authentication token in use is restricted and cannot access the requested resource.
403002Account LimitThe plan limit for a resource has been reached.
403003Forbidden ActionThe plan is restricted and cannot perform this action.

404 NOT FOUND:

CodeTypeDescription
404001Not FoundA resource id was not found.

5xx Range

500 INTERNAL SERVER ERROR:

CodeTypeDescription
500001UnknownPossibly a temporary issue due to downtime. Wait and retry the operation.
503001UnavailableService 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.