Errors and retries

Threetone uses standard HTTP status codes. Read the response body before deciding whether to change the request or retry it.

API error response

Authentication, authorization, conflict, not-found, and server errors use a detail object:

{
  "detail": {
    "status": "invalid_api_key",
    "message": "Invalid API key",
    "request_id": "req_01J..."
  }
}

The status value is machine readable. The message explains the failure, and request_id identifies the request in Threetone logs.

Validation error response

A 422 Unprocessable Entity response uses a list of validation errors:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Use loc to find the invalid path, query parameter, header, or request-body field. Correct the request before sending it again.

Common status codes

Status	Meaning	Action
`400`	The request cannot be processed as submitted.	Correct the request.
`401`	Authentication is missing or invalid.	Check the `x-api-key` header.
`403`	The credential lacks access.	Check permissions, workspace access, and key restrictions.
`404`	The resource was not found or is not visible to the credential.	Check the identifier and workspace.
`409`	The request conflicts with the current resource state.	Refresh the resource and resolve the conflict.
`422`	One or more inputs failed validation.	Fix the fields listed in `detail`.
`429`	The request exceeded a rate limit.	Wait for `Retry-After` before retrying.
`500`	The server could not complete the request.	Retry only when the operation is safe to repeat.

Retry safely

Retry transient 429 and 5xx responses with exponential backoff and jitter. Honor Retry-After when present. Before retrying a mutation, check whether the endpoint supports an idempotency key or whether the resource was already created or updated. Do not automatically retry a validation, authentication, authorization, or not-found response. Keep the X-Request-Id response header, status code, method, path, and timestamp for any failure that needs investigation.

Overview

Agents Platform

Workspace

Shared resources

Utilities

API error response

Validation error response

Common status codes

Retry safely

​API error response

​Validation error response

​Common status codes

​Retry safely

API error response

Validation error response

Common status codes

Retry safely