Errors

Fleet uses standard HTTP status codes: 2xx succeeded, 4xx means the request needs to change, 5xx means something went wrong on our side.

Error bodies are RFC 9457 problem details, sent as application/problem+json:

{
  "type": "https://developers.get-fleet.com/errors/validation_failed",
  "title": "Validation failed",
  "status": 400,
  "code": "validation_failed",
  "detail": "2 parameters are invalid.",
  "instance": "/v1/fuel_logs",
  "request_id": "req_7Hx2mQ9vLk3Pz8Rt1Ws4Yb6N",
  "param": "vehicle_id",
  "errors": [
    { "param": "vehicle_id", "code": "invalid_format", "message": "Invalid UUID" },
    { "param": "quantity", "code": "invalid_union", "message": "Expected a decimal number" }
  ]
}

• Branch on code: it is stable. detail is for people and may change.
• param names the field at fault; errors lists every invalid field on validation_failed.
• type links to the page for that error, with advice.
• Log request_id; it identifies the call in your request log and for support.

Retrying

Status	Retry?
400, 401, 403, 404, 412, 415, 422	No. Fix the request first.
409 duplicate_resource	No. The object exists; look it up and update it.
409 resource_in_use	No. Other records still refer to the object you tried to delete.
409 idempotency_request_in_progress	Yes, after a moment, with the same Idempotency-Key.
429	Yes, after Retry-After seconds.
500, 503, network errors and timeouts	Yes, with exponential backoff and the same Idempotency-Key.

A good default: retry up to 5 times, waiting 0.5 s, 1 s, 2 s, 4 s and 8 s plus random jitter, always reusing the idempotency key of the original request.

All codes

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.