Docs

Errors

Branch on the machine code, never on the text. The text is a fixed English label and can change.

Two formats

WhereFormat
/v1/oauth/token, /revoke, /introspectRFC 6749 §5.2: { "error": "...", "error_description": "..." }. Branch on error.
Everything elseRFC 7807 application/problem+json: type, title, status, detail, instance, correlation_id and the stable code. A validation failure also has errors: [{ field, code, message? }]. Branch on code.
JSON
{
  "error": "invalid_grant",
  "error_description": "The grant is invalid, expired, revoked or was issued to another client"
}
JSON
{
  "type": "https://stracker.io/errors/idempotency-key-reused",
  "title": "Idempotency-Key reused with different payload",
  "status": 422,
  "detail": "Idempotency-Key reused with different payload",
  "instance": "/v1/trips",
  "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
  "code": "IDEMPOTENCY_KEY_REUSED"
}

Quote the correlation_id when you write to support: it finds your request in our logs.

Token endpoint errors

`error`HTTPMeaning and what to do
invalid_request400A parameter is missing, repeated or malformed; Basic and an assertion were sent together; client_id differs from the assertion’s iss. Fix the request.
invalid_client401Client authentication failed: unknown or disabled app, wrong, revoked or expired secret, bad assertion. The same answer for all of them. Carries WWW-Authenticate: Basic realm="stracker".
invalid_grant400The code or refresh token is invalid, expired, spent, revoked or was issued to another app, or the PKCE verifier does not match. Start the flow again.
unauthorized_client400The app may not use this grant type, or (partner apps) is not connected to that tenant.
unsupported_grant_type400Use client_credentials, authorization_code or refresh_token.
invalid_scope400A scope is unknown or outside what your app, the install or the grant allows.
temporarily_unavailable503No signing key can sign right now, or a revocation could not be recorded. Retry with backoff.

Errors on API calls

`code`HTTPMeaning and what to do
VALIDATION_FAILED400The body or query is invalid; errors[] names each field. Fix and resend.
BAD_REQUEST400The request is malformed or not allowed in this state.
AUTH_UNAUTHORIZED401No usable credentials.
OAUTH_TOKEN_INVALID401The access token is expired, revoked or malformed. Get a new one (refresh or request again).
OAUTH_GRANT_REVOKED401The grant or install behind the token was revoked. Ask the user or operator to connect again.
OAUTH_CLIENT_DISABLED401Your app is disabled. Contact us.
OAUTH_ROUTE_NOT_EXPOSED403This route is not open to OAuth tokens. See the reference.
OAUTH_INSUFFICIENT_SCOPE403The token lacks the scope. WWW-Authenticate names it. Ask the operator to approve it.
AUTH_FORBIDDEN403The scope is fine but the user (delegated token) or the app’s role may not do this on that record.
TENANT_SUSPENDED403The operator’s account is suspended.
EXTENSION_NOT_INSTALLED403The operator does not have the api extension.
NOT_FOUND, TRIP_NOT_FOUND404The record does not exist in this tenant.
STALE_TRIP409expectedRev or rev is older than the trip: nothing was written. Read the trip again and decide.
TRIP_INVALID_STATE_TRANSITION409The trip’s status does not allow this (for example rescheduling a trip that has started).
RESOURCE_UNAVAILABLE409A driver or vehicle has an approved unavailability that overlaps the trip.
IDEMPOTENCY_IN_PROGRESS409The same key is still being processed. Retry after Retry-After.
IDEMPOTENCY_KEY_REUSED422The key was used with a different body. Use a new key.
RATE_LIMITED429Too many requests. Wait for Retry-After. See rate limits.
INTERNAL_ERROR500A fault on our side. Retry with backoff and the same idempotency key; quote the correlation_id if it persists.
WEBHOOK_URL_NOT_ALLOWED400The webhook URL is refused; params.reason says why.
WEBHOOK_EVENT_NOT_ALLOWED403Your caller may not subscribe to one of the event types.
WEBHOOK_SUBSCRIPTION_LIMIT_REACHED409The subscription limit is reached; delete one first.
WEBHOOK_SUBSCRIPTION_DISABLED409The subscription is disabled: enable it first.
WEBHOOK_SUBSCRIPTION_NOT_EDITABLE409This caller may not change that subscription: an operator’s user cannot edit or rotate the secret of an app’s subscription.
WEBHOOK_MESSAGE_EXPIRED410The message is too old to redeliver.
Every code of the public API (55)

The codes below are the ones an integration can meet. The title is a fixed English label; branch on the code, never on the text.

CodeMeaning
AUTH_FORBIDDENForbidden
AUTH_UNAUTHORIZEDUnauthorized
BAD_REQUESTBad request
DRIVER_PERSON_NOT_FOUNDDriver not found for this person id
EXTENSION_NOT_INSTALLEDExtension not installed
IDEMPOTENCY_IN_PROGRESSThis request is still being processed. Try again in a moment
IDEMPOTENCY_KEY_REUSEDIdempotency-Key reused with different payload
INTERNAL_ERRORInternal server error
NOT_FOUNDResource not found
OAUTH_APP_ALREADY_INSTALLEDApp is already installed
OAUTH_APP_NOT_INSTALLEDApp is not installed in this workspace
OAUTH_CLIENT_AUTH_METHOD_MISMATCHOauth client auth method mismatch
OAUTH_CLIENT_DISABLEDOAuth client is disabled
OAUTH_CLIENT_KEY_DUPLICATEOauth client key duplicate
OAUTH_CLIENT_KEY_INVALIDOauth client key invalid
OAUTH_CLIENT_KEY_LIMIT_REACHEDOauth client key limit reached
OAUTH_CLIENT_SECRET_LIMIT_REACHEDOAuth client secret limit reached
OAUTH_CONNECTION_APPROVAL_WIDENSApproval asks for more than the request
OAUTH_CONNECTION_LINK_EXPIREDConnection request link has expired
OAUTH_CONNECTION_LINK_INVALIDConnection request link is not valid
OAUTH_CONNECTION_REQUEST_CLOSEDConnection request is closed
OAUTH_CONSENT_NOT_ALLOWEDConsent not allowed
OAUTH_GRANT_REVOKEDAccess grant was revoked
OAUTH_GRANT_TYPE_NOT_ALLOWEDGrant type not allowed for this client
OAUTH_HANDOFF_ALREADY_VIEWEDCredentials were already shown
OAUTH_HANDOFF_CODE_INVALIDVerification code is not valid
OAUTH_HANDOFF_CODE_LIMITVerification code limit reached
OAUTH_HANDOFF_EXPIREDCredential link has expired
OAUTH_HANDOFF_LINK_INVALIDCredential link is not valid
OAUTH_HANDOFF_LOCKEDCredential link is locked
OAUTH_INSTALL_REQUEST_CLOSEDInstall request is closed
OAUTH_INSUFFICIENT_SCOPEAccess token scope is insufficient
OAUTH_REAUTH_REQUIREDRecent sign-in required
OAUTH_REDIRECT_URI_MISMATCHRedirect URI does not match
OAUTH_REDIRECT_URI_NOT_ALLOWEDRedirect URI not allowed
OAUTH_ROUTE_NOT_EXPOSEDThis route is not available to API access tokens
OAUTH_SCOPE_NOT_ALLOWEDScope is not allowed
OAUTH_SIGNING_KEY_NOT_REVOCABLESigning key cannot be revoked
OAUTH_TENANT_REQUIREDA tenant is required
OAUTH_TOKEN_INVALIDAccess token is invalid
OAUTH_WORKSPACE_CHANGEDWorkspace changed
RATE_LIMITEDToo many requests
RESOURCE_UNAVAILABLEResource unavailable
STALE_TRIPStale trip
TENANT_SUSPENDEDTenant account suspended — contact your administrator
TRIP_INVALID_STATE_TRANSITIONTrip invalid state transition
TRIP_NOT_FOUNDTrip not found
VALIDATION_FAILEDValidation failed
WEBHOOK_EVENT_NOT_ALLOWEDWebhook event not allowed
WEBHOOK_MESSAGE_EXPIREDWebhook message expired
WEBHOOK_SIGNATURE_INVALIDWebhook signature invalid
WEBHOOK_SUBSCRIPTION_DISABLEDWebhook subscription disabled
WEBHOOK_SUBSCRIPTION_LIMIT_REACHEDWebhook subscription limit reached
WEBHOOK_SUBSCRIPTION_NOT_EDITABLEWebhook subscription not editable
WEBHOOK_URL_NOT_ALLOWEDWebhook url not allowed

Each operation in the reference lists the statuses it can return and what causes them.