Two formats
| Where | Format |
|---|---|
/v1/oauth/token, /revoke, /introspect | RFC 6749 §5.2: { "error": "...", "error_description": "..." }. Branch on error. |
| Everything else | RFC 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. |
{
"error": "invalid_grant",
"error_description": "The grant is invalid, expired, revoked or was issued to another client"
}{
"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` | HTTP | Meaning and what to do |
|---|---|---|
invalid_request | 400 | A 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_client | 401 | Client 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_grant | 400 | The 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_client | 400 | The app may not use this grant type, or (partner apps) is not connected to that tenant. |
unsupported_grant_type | 400 | Use client_credentials, authorization_code or refresh_token. |
invalid_scope | 400 | A scope is unknown or outside what your app, the install or the grant allows. |
temporarily_unavailable | 503 | No signing key can sign right now, or a revocation could not be recorded. Retry with backoff. |
Errors on API calls
| `code` | HTTP | Meaning and what to do |
|---|---|---|
VALIDATION_FAILED | 400 | The body or query is invalid; errors[] names each field. Fix and resend. |
BAD_REQUEST | 400 | The request is malformed or not allowed in this state. |
AUTH_UNAUTHORIZED | 401 | No usable credentials. |
OAUTH_TOKEN_INVALID | 401 | The access token is expired, revoked or malformed. Get a new one (refresh or request again). |
OAUTH_GRANT_REVOKED | 401 | The grant or install behind the token was revoked. Ask the user or operator to connect again. |
OAUTH_CLIENT_DISABLED | 401 | Your app is disabled. Contact us. |
OAUTH_ROUTE_NOT_EXPOSED | 403 | This route is not open to OAuth tokens. See the reference. |
OAUTH_INSUFFICIENT_SCOPE | 403 | The token lacks the scope. WWW-Authenticate names it. Ask the operator to approve it. |
AUTH_FORBIDDEN | 403 | The scope is fine but the user (delegated token) or the app’s role may not do this on that record. |
TENANT_SUSPENDED | 403 | The operator’s account is suspended. |
EXTENSION_NOT_INSTALLED | 403 | The operator does not have the api extension. |
NOT_FOUND, TRIP_NOT_FOUND | 404 | The record does not exist in this tenant. |
STALE_TRIP | 409 | expectedRev or rev is older than the trip: nothing was written. Read the trip again and decide. |
TRIP_INVALID_STATE_TRANSITION | 409 | The trip’s status does not allow this (for example rescheduling a trip that has started). |
RESOURCE_UNAVAILABLE | 409 | A driver or vehicle has an approved unavailability that overlaps the trip. |
IDEMPOTENCY_IN_PROGRESS | 409 | The same key is still being processed. Retry after Retry-After. |
IDEMPOTENCY_KEY_REUSED | 422 | The key was used with a different body. Use a new key. |
RATE_LIMITED | 429 | Too many requests. Wait for Retry-After. See rate limits. |
INTERNAL_ERROR | 500 | A fault on our side. Retry with backoff and the same idempotency key; quote the correlation_id if it persists. |
WEBHOOK_URL_NOT_ALLOWED | 400 | The webhook URL is refused; params.reason says why. |
WEBHOOK_EVENT_NOT_ALLOWED | 403 | Your caller may not subscribe to one of the event types. |
WEBHOOK_SUBSCRIPTION_LIMIT_REACHED | 409 | The subscription limit is reached; delete one first. |
WEBHOOK_SUBSCRIPTION_DISABLED | 409 | The subscription is disabled: enable it first. |
WEBHOOK_SUBSCRIPTION_NOT_EDITABLE | 409 | This caller may not change that subscription: an operator’s user cannot edit or rotate the secret of an app’s subscription. |
WEBHOOK_MESSAGE_EXPIRED | 410 | The 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.
| Code | Meaning |
|---|---|
AUTH_FORBIDDEN | Forbidden |
AUTH_UNAUTHORIZED | Unauthorized |
BAD_REQUEST | Bad request |
DRIVER_PERSON_NOT_FOUND | Driver not found for this person id |
EXTENSION_NOT_INSTALLED | Extension not installed |
IDEMPOTENCY_IN_PROGRESS | This request is still being processed. Try again in a moment |
IDEMPOTENCY_KEY_REUSED | Idempotency-Key reused with different payload |
INTERNAL_ERROR | Internal server error |
NOT_FOUND | Resource not found |
OAUTH_APP_ALREADY_INSTALLED | App is already installed |
OAUTH_APP_NOT_INSTALLED | App is not installed in this workspace |
OAUTH_CLIENT_AUTH_METHOD_MISMATCH | Oauth client auth method mismatch |
OAUTH_CLIENT_DISABLED | OAuth client is disabled |
OAUTH_CLIENT_KEY_DUPLICATE | Oauth client key duplicate |
OAUTH_CLIENT_KEY_INVALID | Oauth client key invalid |
OAUTH_CLIENT_KEY_LIMIT_REACHED | Oauth client key limit reached |
OAUTH_CLIENT_SECRET_LIMIT_REACHED | OAuth client secret limit reached |
OAUTH_CONNECTION_APPROVAL_WIDENS | Approval asks for more than the request |
OAUTH_CONNECTION_LINK_EXPIRED | Connection request link has expired |
OAUTH_CONNECTION_LINK_INVALID | Connection request link is not valid |
OAUTH_CONNECTION_REQUEST_CLOSED | Connection request is closed |
OAUTH_CONSENT_NOT_ALLOWED | Consent not allowed |
OAUTH_GRANT_REVOKED | Access grant was revoked |
OAUTH_GRANT_TYPE_NOT_ALLOWED | Grant type not allowed for this client |
OAUTH_HANDOFF_ALREADY_VIEWED | Credentials were already shown |
OAUTH_HANDOFF_CODE_INVALID | Verification code is not valid |
OAUTH_HANDOFF_CODE_LIMIT | Verification code limit reached |
OAUTH_HANDOFF_EXPIRED | Credential link has expired |
OAUTH_HANDOFF_LINK_INVALID | Credential link is not valid |
OAUTH_HANDOFF_LOCKED | Credential link is locked |
OAUTH_INSTALL_REQUEST_CLOSED | Install request is closed |
OAUTH_INSUFFICIENT_SCOPE | Access token scope is insufficient |
OAUTH_REAUTH_REQUIRED | Recent sign-in required |
OAUTH_REDIRECT_URI_MISMATCH | Redirect URI does not match |
OAUTH_REDIRECT_URI_NOT_ALLOWED | Redirect URI not allowed |
OAUTH_ROUTE_NOT_EXPOSED | This route is not available to API access tokens |
OAUTH_SCOPE_NOT_ALLOWED | Scope is not allowed |
OAUTH_SIGNING_KEY_NOT_REVOCABLE | Signing key cannot be revoked |
OAUTH_TENANT_REQUIRED | A tenant is required |
OAUTH_TOKEN_INVALID | Access token is invalid |
OAUTH_WORKSPACE_CHANGED | Workspace changed |
RATE_LIMITED | Too many requests |
RESOURCE_UNAVAILABLE | Resource unavailable |
STALE_TRIP | Stale trip |
TENANT_SUSPENDED | Tenant account suspended — contact your administrator |
TRIP_INVALID_STATE_TRANSITION | Trip invalid state transition |
TRIP_NOT_FOUND | Trip not found |
VALIDATION_FAILED | Validation failed |
WEBHOOK_EVENT_NOT_ALLOWED | Webhook event not allowed |
WEBHOOK_MESSAGE_EXPIRED | Webhook message expired |
WEBHOOK_SIGNATURE_INVALID | Webhook signature invalid |
WEBHOOK_SUBSCRIPTION_DISABLED | Webhook subscription disabled |
WEBHOOK_SUBSCRIPTION_LIMIT_REACHED | Webhook subscription limit reached |
WEBHOOK_SUBSCRIPTION_NOT_EDITABLE | Webhook subscription not editable |
WEBHOOK_URL_NOT_ALLOWED | Webhook url not allowed |
Each operation in the reference lists the statuses it can return and what causes them.