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.

StatusCodeWhat it meansWhat to do
400VALIDATION_ERRORA value fails validation, or the body isn't valid JSON. errors lists each one.Fix the request.
400BAD_REQUESTThe request sends more than one credential.Send only Authorization: Bearer.
401UNAUTHORIZEDThe 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.
402INACTIVE_SUBSCRIPTIONThe 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.
403INSUFFICIENT_SCOPEThe 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.
404NOT_FOUNDThe path matches no route.Check it against the OpenAPI document.
408REQUEST_TIMEOUTWe didn't receive the whole request in time.Retry.
413PAYLOAD_TOO_LARGEThe body is larger than we accept.Send less.
422BALLISTICS_ERRORThe request is valid, but the engine has no answer for it.Change the inputs.
429RATE_LIMITEDA budget is spent for the current window.Wait Retry-After seconds.
500INTERNAL_SERVER_ERRORSomething failed on our side.Retry.
503SERVICE_UNAVAILABLEThe 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

ResponseWhat to do
429 with code RATE_LIMITEDWait Retry-After seconds, then retry.
503Wait Retry-After seconds, then retry, up to 3 times.
408Retry with exponential backoff, up to 3 times.
Any other 5xxRetry with exponential backoff, up to 3 times. All nine routes are compute calls or reads, which are safe to repeat.
Anything elseDon'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": "..."}.

errorWhat it means
invalid_grantThe 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_clientThe client_id is unknown or suspended, or the secret is wrong. See Secrets and the binding.
invalid_requestThe 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_targetresource isn't the one the code or refresh token was issued for. The token stays usable.
unsupported_grant_typegrant_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.