Error codes

Errors are RFC 9457 problem details. Branch on code(stable) rather than detail (human-readable, may change). See Errors for handling advice.

Status	Code	Meaning
401	authentication_required	The request had no API key. Send it as Authorization: Bearer flt_….
401	invalid_api_key	The API key is malformed, unknown, or belongs to the other environment (live vs test).
401	api_key_revoked	The API key was revoked in Settings → Developers.
401	api_key_expired	The API key passed its expiry date. Create or roll a key.
403	ip_not_allowed	The key has an IP allowlist and the request came from an address outside it.
403	insufficient_scope	The API key lacks the scope this endpoint needs. The required_scope field names it.
403	permission_denied	The organization's "API integrations" role does not allow this action. An admin can change it in Settings → Roles.
400	invalid_json	The request body is not valid JSON.
400	validation_failed	One or more parameters are missing or invalid. errors lists each one.
400	unsupported_version	The Fleet-Version header names a version this API does not serve.
404	resource_not_found	No object with that id exists in your organization.
404	route_not_found	No endpoint matches this method and path.
409	duplicate_resource	An object with the same unique value (for example a vehicle number) already exists.
409	resource_in_use	Other records still refer to this object (for example fuel logs that name this vendor), so it cannot be deleted.
409	invalid_state	The object is not in a state that allows this action (for example approving a request that was never submitted).
409	idempotency_request_in_progress	A request with this Idempotency-Key is still being processed. Retry shortly.
412	precondition_failed	The object changed since you read it: its ETag no longer matches If-Match. Fetch it again and retry.
413	payload_too_large	The request body exceeds 1 MB, or 10 MB for a file upload.
415	unsupported_media_type	Send request bodies as application/json.
422	reference_not_found	An id in the request (for example vehicle_id) does not exist in your organization.
422	idempotency_key_reused	This Idempotency-Key was already used with a different request body or path in the last 24 hours.
429	rate_limited	Too many requests for this API key. Wait for the number of seconds in Retry-After.
500	internal_error	Something went wrong on our side. Retrying with the same Idempotency-Key is safe.
503	service_unavailable	The API is temporarily unavailable. Retry with exponential backoff.