> For AI agents: the complete documentation index is at
> [https://docs.retrocast.com/llms.txt](https://docs.retrocast.com/llms.txt) — every page is also available as
> markdown by appending `.md` to its URL.


# Error handling

Every error comes back as a JSON problem document
([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)) with the content type
`application/problem+json`:

```json
{
  "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

| 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](https://app.retrocast.com/?settings=credit). | 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:

```json
{"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 support@theforecastingcompany.com.
