API errors

Unauthorized

The request carried no usable credentials: the bearer token is missing, invalid or expired, or the client credentials were rejected.

401application/problem+json

What it means

Every endpoint except POST /auth/token requires an Authorization: Bearer {token} header. This error means that header was missing, the token in it did not check out, or the token has expired. On the token endpoint itself it means the client_id and client_secret were rejected.

Tokens are valid for 24 hours from issue, so a long-running integration will see this on schedule if it never refreshes.

401 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or expired token"
}

How to handle it

Request a fresh token from POST /auth/token and retry the original request once with it.
Cache tokens for their 24 hour lifetime instead of requesting one per call, and refresh shortly before expiry.
Check you are sending the right environment's credentials. Sandbox and production credentials are separate, and each only works against its own base URL.
Do not loop on 401. If a freshly issued token is still rejected, the credentials themselves are the problem; contact Firsty support.

Authentication guide Authentication reference Errors reference

What it means

How to handle it

Related