Errors

One JSON error envelope, stable codes and request ids.

Draft

Every /v1 error uses the same envelope. Branch on code (stable, specific); type is a small vocabulary tied to the HTTP status; message is for humans and may change.

Error envelopejson

{
  "error": {
    "type": "forbidden",
    "code": "vehicle_not_accessible",
    "message": "…",
    "request_id": "…"
  }
}

Types

invalid_request, unauthorized, forbidden, not_found, rate_limited, conflict, payment_required, gone, unprocessable, service_unavailable, server_error.

Suspended scopes

FleetBold can temporarily suspend one scope of your app. Requests that need it answer 403 scope_suspended with scope, a public reason and until (ISO-8601 UTC; absent while the suspension has no end date). The scope stays granted but inactive, new connections still work, and the console shows a banner. Retry after until or contact FleetBold. A token that never had the scope still gets insufficient_scope.

Request ids

Every response carries X-Request-Id. Include it when you contact support.

/oauth/token, /oauth/revoke and /oauth/introspect answer standard OAuth errors (RFC 6749), not this envelope. The authorization step reports its errors on the redirect to your redirect_uri (error, state, iss, usually error_description): see the OAuth guide.