The Forecasting API is now v1. API v0 is deprecated and stops working on 20 December 2026. Move to v1
The Forecasting Company Logo

Error handling

Every error comes back as a JSON problem document (RFC 9457) with the content type application/problem+json:

JSONCode
{ "type": "about:blank", "title": "Unprocessable Entity", "status": 422, "code": "unprocessable", "detail": "unknown target column `revenue`" }

code names the kind of error and is stable: match on it rather than on title or detail. detail says what went wrong with this request, for a person to read, and its wording may change.

A few errors are returned before the request reaches the forecasting service: 401 for a missing or invalid API key, 402 when your organization's credit is used up, and 429 when you send too many requests. These are problem documents too, but carry no code; tell them apart by status.

Status codes

StatuscodeMeaningRetry?
400bad_requestThe request is malformed: unreadable JSON, or a field of the wrong type.No, fix the request
401No API key was sent, or it is not valid.No
402Your organization's credit is used up. Top up in Retrocast.After topping up
403forbiddenThe API key was refused.No
406not_acceptableThe Accept header names no format the forecast can be sent in.No, fix the header
413too_largeThe request body is too large. Send the data as a file instead of inline.No
422unprocessableThe request is well formed but can't be forecast: the data doesn't match its schema, a setting doesn't fit the data, or the model can't serve it. detail says which.No, fix the request
429Too many requests.Yes, after Retry-After
500internalAn unexpected failure in the service.Yes, with backoff
502bad_upstreamThe model returned a response the service could not read.Yes, with backoff
503upstream_unavailableThe model is unavailable.Yes, after Retry-After if sent
504upstream_timeoutThe model did not answer in time.Yes, after Retry-After if sent

Errors in a streamed response

With Accept: application/x-ndjson or application/vnd.msgpack, series forecasts are sent as they are ready, so the status 200 goes out before the whole forecast is done. If a failure cuts the stream short, the series forecasts already sent are followed by one error record holding a problem document:

JSONCode
{"error": {"type": "about:blank", "title": "Service Unavailable", "status": 503, "code": "upstream_unavailable", "detail": "…"}}

The forecasts before it are valid. Every stream ends with a {"usage": …} record, after the error record if there is one: a stream that ends without it was cut off in transit.

Questions? Email [email protected].

Last modified on