Error Reference

Error format and a complete reference of API status codes with resolution steps.

The Claret API reports errors using RFC 9457 "Problem Details for HTTP APIs". Error responses use the application/problem+json content type and a consistent body shape.

Error format

{
  "type": "https://httpstatuses.com/422",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request parameters are invalid.",
  "request_id": "5f8a1c2e-...",
  "errors": {
    "data.0.quantity": ["The quantity field must be a number."]
  }
}

Field	Always present	Description
type	Yes	A URI identifying the problem type.
title	Yes	A short, human-readable summary of the problem.
status	Yes	The HTTP status code, repeated in the body.
detail	Yes	A human-readable explanation specific to this occurrence.
request_id	Yes	Correlates the error with server logs. Include it in support requests.
errors	No	Field-level validation messages, present on 422 responses.

Every response also carries an X-Request-ID header. When reporting a problem to support, include the request_id so the exact request can be traced.

Status codes

Success

Code	Meaning	Notes
200 OK	Request succeeded.	Synchronous reads and writes.
201 Created	Resource created.	Token creation.
202 Accepted	Work accepted for async processing.	Compute and workflow endpoints. Returns a job_id to poll.

Client errors

Code	Title	What it means	How to resolve
400	Bad Request	The request was malformed (for example, invalid JSON).	Check the request body and query string syntax.
401	Unauthorized	The token is missing, malformed, or revoked.	Send a valid Authorization: Bearer {token} header. Create a new token if it was revoked. Ensure Accept: application/json is set.
402	Insufficient Credits	The tenant's credit balance cannot cover the request.	Wait for the monthly credit refresh, or contact support. See API Credits & Usage.
403	Forbidden	The token lacks the required scope, or the token creator lacks module permission for the resource.	Create a token with the required scope, or provision it from a user who can see the resource in the Claret UI.
404	Not Found	The resource or route does not exist.	Check the URL, the {tenant} segment, and the resource ID.
409	Conflict	A conflicting operation is already in progress, or a duplicate request was detected.	For imports, wait for the in-progress job to finish. For retries, reuse the same Idempotency-Key.
422	Validation Error	The payload failed validation.	Read the errors object for field-level messages and correct the input.
429	Too Many Requests	A rate-limit bucket is empty.	Wait the number of seconds in the Retry-After header, then retry with backoff. See Rate Limiting.

Server errors

Code	Title	What it means	How to resolve
500	Server Error	An unexpected error occurred.	Retry after a short delay. If it persists, contact support with the request_id.
503	Service Unavailable	A dependency (such as the rate-limit or credit store) is temporarily unavailable.	Retry after a short delay. This is rare; the API is configured to fail open by default.

Validation errors in detail

422 responses include an errors object keyed by the field path that failed. For array payloads (such as workflow sync), the path includes the row index:

{
  "type": "https://httpstatuses.com/422",
  "title": "Validation Error",
  "status": 422,
  "detail": "The given data was invalid.",
  "request_id": "5f8a1c2e-...",
  "errors": {
    "data.0.item_name": ["The item name field is required."],
    "data.2.uom": ["The selected uom is invalid."]
  }
}

Use the index to locate the offending record in your payload.

Related documentation

• Authentication & Tokens — resolving 401 and 403.

• Scopes Reference — resolving scope-related 403.

• API Credits & Usage — resolving 402.

• Rate Limiting — resolving 429.