# Errors and What to Do

## Calling the API (`/api/v1/...`)

Errors come back as `application/problem+json` (RFC 9457). Switch on `code`
(and on `ballisticsError` when there is one), not on `title` or `detail`,
which are text for a person. New codes can appear, so have a fallback:
[don't retry it](#when-to-retry), show `detail`, and log the request ID.
The `Problem` schema in the [OpenAPI document](/documentation/developers/calling-the-api/#openapi-document)
lists every code and member.

| Status | Code | What it means | What to do |
|---|---|---|---|
| 400 | `VALIDATION_ERROR` | A value fails validation, or the body isn't valid JSON. `errors` lists each one. | Fix the request. |
| 400 | `BAD_REQUEST` | The request sends more than one credential. | Send only `Authorization: Bearer`. |
| 401 | `UNAUTHORIZED` | The token is missing, expired or revoked, its sign-in has ended, or your app is suspended. | Refresh. If the refresh gets `invalid_grant`, send the user through authorization again. If the token endpoint answers `invalid_client` to a request that used to work, read its `error_description`: `this app is suspended` means contact us; otherwise check whether your [secret](/documentation/developers/getting-access/#secrets) retired or was revoked. |
| 402 | `INACTIVE_SUBSCRIPTION` | The user's subscription has lapsed. The connection stays intact. | Prompt the user to renew, linking their [subscription page](https://www.precisioncutarchery.com/app/account/subscription/). Once they renew, the same tokens work again. The [subscription check](/documentation/developers/calling-the-api/#subscription-check) never answers `402`. |
| 403 | `INSUFFICIENT_SCOPE` | The token lacks the scope the route needs; `WWW-Authenticate` names it. | Send the user through authorization again requesting it (a new sign-in, which ends none: see [Tokens](/documentation/developers/tokens/#several-devices)), or contact us if your app may not request it. |
| 404 | `NOT_FOUND` | The path matches no route. | Check it against the OpenAPI document. |
| 408 | `REQUEST_TIMEOUT` | We didn't receive the whole request in time. | [Retry](#when-to-retry). |
| 413 | `PAYLOAD_TOO_LARGE` | The body is larger than we accept. | Send less. |
| 422 | `BALLISTICS_ERROR` | The request is valid, but the engine has no answer for it. | Change the inputs. |
| 429 | `RATE_LIMITED` | A budget is spent for the current window. | Wait `Retry-After` seconds. |
| 500 | `INTERNAL_SERVER_ERROR` | Something failed on our side. | [Retry](#when-to-retry). |
| 503 | `SERVICE_UNAVAILABLE` | The engine didn't finish in time (`ballisticsError` `SOLVER_TIMEOUT`). | Retry after `Retry-After`, up to 3 times. |

The `ballisticsError` values are in the `Problem` schema. A `422` isn't
retried; a `503` `SOLVER_TIMEOUT` is. For example, `analyze/trajectory`
answers `422` for a `zeroRangeMeters` the arrow can't reach:

```json
{
  "type": "about:blank",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "The target cannot be reached with the given parameters.",
  "instance": "https://precisioncutarchery.com/requests/6f1c2b0e-3d4a-4b5c-8d6e-7f8091a2b3c4",
  "code": "BALLISTICS_ERROR",
  "ballisticsError": "CANNOT_REACH_TARGET"
}
```

### Request IDs

Every response the API answers carries `X-Request-ID`, an opaque ID of at
most 64 characters. An error body repeats it in `instance`. Log the ID
with every failed call, and include it when you contact support.

### Rate limits

[Getting access](/documentation/developers/getting-access/#rate-limits)
gives the current limits. On a `429`, honor `Retry-After`. On a call we
serve, the `RateLimit-Policy` and `RateLimit` headers describe the user's
budget for the area, which every app they use draws on, not your app's
budgets, so pace your app from your own count of its requests. A browser
app can read these headers (see
[CORS](/documentation/developers/calling-the-api/#cors)). They can be
missing, so `Retry-After` is what to depend on.

### When to retry

| Response | What to do |
|---|---|
| `429` with `code` `RATE_LIMITED` | Wait `Retry-After` seconds, then retry. |
| `503` | Wait `Retry-After` seconds, then retry, up to 3 times. |
| `408` | Retry with exponential backoff, up to 3 times. |
| Any other `5xx` | Retry with exponential backoff, up to 3 times. All nine routes are compute calls or reads, which are safe to repeat. |
| Anything else | Don't retry. Show `detail` and log the request ID. |

## The token endpoint (`POST /oauth/token`)

Errors follow RFC 6749 §5.2: HTTP 400 (401 for `invalid_client`) with a
JSON body of `{"error": "...", "error_description": "..."}`.

| `error` | What it means |
|---|---|
| `invalid_grant` | The code or refresh token is wrong, expired, revoked, already used, or presented with the wrong `redirect_uri`, `code_verifier` or client. A refresh token sent again can get a fresh pair or end its sign-in: [Tokens](/documentation/developers/tokens/#refresh-tokens-rotate) has the table. |
| `invalid_client` | The `client_id` is unknown or suspended, or the secret is wrong. See [Secrets](/documentation/developers/getting-access/#secrets) and [the binding](/documentation/developers/getting-access/#mobile-app-with-a-backend). |
| `invalid_request` | The request is malformed: a required parameter is missing or repeated, the client authenticated two ways, or the body isn't `application/x-www-form-urlencoded`. |
| `invalid_target` | `resource` isn't the one the code or refresh token was issued for. The token stays usable. |
| `unsupported_grant_type` | `grant_type` isn't `authorization_code` or `refresh_token`. |

An exchange refused for a wrong `redirect_uri`, `code_verifier`, client or
`resource` doesn't spend the code: fix the parameter and send the same
code again within its 60 seconds.

The token and revocation endpoints answer a rate-limit refusal with a
`429`, `Retry-After`, and `error` `temporarily_unavailable`. A token you
asked to revoke is still live, so send the revocation again after the wait.

## The authorize endpoint (`GET /oauth/authorize`)

If `client_id` is unknown or `redirect_uri` doesn't match a registered one,
we **never redirect**: we show our own error page, because there's no
redirect target we can trust. A suspended app, a repeated parameter and a
`state` over 1024 characters get the same page. In development the page
says why, because it's you or a test account looking at it; for a live
app it says only that the connection didn't work. Compare your
`redirect_uri` with the registered one, character for character.

Every other problem redirects back to your `redirect_uri` with `error` and
`error_description`. Switch on `error`: the description is text for a
developer. The ones you'll meet are `invalid_scope` (a scope outside your
app's limit, or none), `invalid_request` (a missing or malformed PKCE
challenge, or a `response_mode` other than `query`), `invalid_target`
(`resource` isn't the issuer) and `unsupported_response_type`.
`access_denied` is the user pressing Deny, going back from our screen
saying your app is in development and they aren't a test account, or going
back from the renewal prompt.

## The revocation endpoint (`POST /oauth/revoke`)

Revocation answers `200` with an empty body for any token, including an
unknown or another app's, and fails with the token endpoint's errors.
