Module 09 · API

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.

View as Markdown

On this page

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.
`method_not_allowed`	405	Use a method from the `Allow` header.
`signed_out`	401	Send the account's session token. See Authentication.
`forbidden`	403	The account may not use the route.
`rate_limited`	429	Wait for the `Retry-After` seconds before trying again. See Versioning and limits.
`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.
`try_used_up`	429	The visitor used every free prompt of the free trial. The error carries `promptsLeft`.
`try_ended`	503	The free trial is used up for this month. The error carries `reopensOn`, the day it opens again (UTC).
`try_busy`	429	A prompt is already running, or too many run at once. Wait for the answer, then try again. A `Retry-After` header says how long when it is the second case.
`try_refused`	403, 503	The request did not pass the check that a person sent it, or the check could not run. Open the page in a browser.
`try_failed`	502	The free trial could not answer the prompt. The error says how many prompts are left.
`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. The free trial's errors add fields inside error where they help (reopensOn, promptsLeft).

Still stuck?#

Write to hey@stellarfirm.ai with the error.code and the time of the request.

Error codes#

Still stuck?#

Related#