Error handling
Every error comes back as a JSON problem document
(RFC 9457) with the content type
application/problem+json:
Code
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
| Status | code | Meaning | Retry? |
|---|---|---|---|
400 | bad_request | The request is malformed: unreadable JSON, or a field of the wrong type. | No, fix the request |
401 | No API key was sent, or it is not valid. | No | |
402 | Your organization's credit is used up. Top up in Retrocast. | After topping up | |
403 | forbidden | The API key was refused. | No |
406 | not_acceptable | The Accept header names no format the forecast can be sent in. | No, fix the header |
413 | too_large | The request body is too large. Send the data as a file instead of inline. | No |
422 | unprocessable | The 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 |
429 | Too many requests. | Yes, after Retry-After | |
500 | internal | An unexpected failure in the service. | Yes, with backoff |
502 | bad_upstream | The model returned a response the service could not read. | Yes, with backoff |
503 | upstream_unavailable | The model is unavailable. | Yes, after Retry-After if sent |
504 | upstream_timeout | The 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:
Code
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].

