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, show detail, and log the request ID.
The Problem schema in the 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 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. Once they renew, the same tokens work again. The 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), 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. |
| 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. |
| 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:
{
"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
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). 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 has the table. |
invalid_client | The client_id is unknown or suspended, or the secret is wrong. See Secrets and the binding. |
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.