Analytics and advertising cookies

Google Analytics, Leadsy and the TikTok Pixel stay off until you accept. The help chat starts once you have chosen. Read our Privacy Policy.

Skip to content
StellarFirmStellarFirm
Join waitlist
Mission manual
Esc

Type a word to search every page. Try , or .

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"
  }
}
FieldMeaning
codeA stable, machine-readable code.
messageWhat went wrong, in one plain sentence.
hintWhat to do next.
docsThis page.

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

Error codes#

CodeStatusWhat to do
not_found404The address is not a route. Check the OpenAPI file.
method_not_allowed405Use a method from the Allow header.
signed_out401Send the account's session token. See Authentication.
trial_ended403The trial has ended. The account needs a licence.
forbidden403The account may not use the route.
invalid_request400The request is not valid. Check it against the OpenAPI file.
invalid_token400The link or token is not valid. Use the link exactly as sent.
not_configured503Sign-in is not set up on this deployment. Try again later.
balance_unavailable503The balance could not be read. Try again in a few seconds.
unavailable503StellarFirm could not answer. Try again in a few seconds.
upstream_failed502A service StellarFirm relies on did not answer. Try again.
too_large413The request is too large. Send a smaller one.
internal_error500Something 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.