# StellarFirm API errors

> The one error shape every StellarFirm API route uses, the HTTP statuses it comes with, and every error code with what to do about it.

Every failure from a public StellarFirm API route is JSON with the same shape. Branch on `error.code`: it is stable. The `message` and `hint` are for people and may be reworded.

```json
{
  "error": {
    "code": "not_found",
    "message": "There is no API route at /api/nothing-here.",
    "hint": "Read the route list at /openapi.json, or start at /docs/api.",
    "docs": "https://stellarfirm.ai/docs/api/errors"
  }
}
```

| Field | Meaning |
| --- | --- |
| `code` | A stable, machine-readable code. |
| `message` | What went wrong, in one plain sentence. |
| `hint` | What to do next. |
| `docs` | This page. |

Failures are never cached. A `405` also carries an `Allow` header that lists the methods the route accepts.

## Error codes

| Code | Status | What to do |
| --- | --- | --- |
| `not_found` | 404 | The address is not a route. Check the [OpenAPI file](https://stellarfirm.ai/openapi.json). |
| `method_not_allowed` | 405 | Use a method from the `Allow` header. |
| `signed_out` | 401 | Send the account's session token. See [Authentication](/docs/api/authentication). |
| `trial_ended` | 403 | The trial has ended. The account needs a licence. |
| `forbidden` | 403 | The account may not use the route. |
| `invalid_request` | 400 | The request is not valid. Check it against the OpenAPI file. |
| `invalid_token` | 400 | The link or token is not valid. Use the link exactly as sent. |
| `not_configured` | 503 | Sign-in is not set up on this deployment. Try again later. |
| `balance_unavailable` | 503 | The balance could not be read. Try again in a few seconds. |
| `unavailable` | 503 | StellarFirm could not answer. Try again in a few seconds. |
| `upstream_failed` | 502 | A service StellarFirm relies on did not answer. Try again. |
| `too_large` | 413 | The request is too large. Send a smaller one. |
| `internal_error` | 500 | Something went wrong on our side. Try again. |

Routes that belong to the signed-in app can answer other codes. They keep the same shape.

## Still stuck?

Write to hey@astrocode.tech with the `error.code` and the time of the request.

## Related

- [Endpoints](/docs/api/endpoints)
- [Authentication](/docs/api/authentication)

---

Source: https://stellarfirm.ai/docs/api/errors