Error Reference

All Lathe Studio API errors follow a consistent envelope format, making them easy to handle programmatically.

Error Envelope#

Every 4xx and 5xx response returns JSON with this shape:

{
  "error": "invalid_request",
  "message": "The 'name' field is required.",
  "details": {
    "field": "name"
  }
}

Field	Type	Description
`error`	string	Machine-readable error code. Use this for programmatic handling.
`message`	string	Human-readable description. Safe to display to end users.
`details`	object \| null	Optional. Additional context such as the specific field that failed validation, limit values, etc.

HTTP Status Codes#

Status	Error Code	When It Occurs
400	`invalid_request`	Request body or parameters are malformed or missing required fields
401	`unauthorized`	Missing, malformed, or revoked API key
403	`forbidden`	API key lacks the required scope for this operation
404	`not_found`	Resource does not exist, or the key cannot access it
409	`conflict`	Request conflicts with existing state (e.g. duplicate idempotency key with different body)
422	`unprocessable`	Request is well-formed but semantically invalid (e.g. `release_id` references a non-existent release)
429	`rate_limit_exceeded`	Monthly or per-minute rate limit exceeded
500	`internal_error`	Unexpected server error
503	`service_unavailable`	Planned maintenance or temporary outage

Error Examples#

400 — Missing required field

{
  "error": "invalid_request",
  "message": "The 'name' field is required.",
  "details": {
    "field": "name"
  }
}

401 — Invalid API key

{
  "error": "unauthorized",
  "message": "Invalid or expired API key. Check your Authorization header."
}

Check that your header is formatted as Authorization: Bearer pt_live_... (with a space after Bearer).

403 — Missing scope

{
  "error": "forbidden",
  "message": "This API key does not have the 'builds:create' scope.",
  "details": {
    "required_scope": "builds:create"
  }
}

Create a new API key with the required scopes. Scopes cannot be added to existing keys.

404 — Resource not found

{
  "error": "not_found",
  "message": "Build not found."
}

The resource either doesn't exist or belongs to a different organization. Verify the ID.

422 — Semantic validation error

{
  "error": "unprocessable",
  "message": "The specified release_id does not exist in this project.",
  "details": {
    "field": "release_id",
    "value": "rel_01HXYZ"
  }
}

429 — Rate limit exceeded

{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded your monthly API call limit.",
  "details": {
    "limit": 1000,
    "reset_at": "2026-04-01T00:00:00Z"
  }
}

See the X-RateLimit-Reset header for when the limit resets. See Rate Limits for retry guidance.

500 — Internal error

{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again or contact support."
}

Retry with exponential backoff. If the error persists, contact support@lathe.studio with the timestamp and endpoint.

Idempotency#

For POST requests, include an Idempotency-Key header to safely retry without creating duplicate resources:

Idempotency-Key: my-pipeline-run-12345

If a request with the same key succeeds, subsequent identical requests return the original response. If the body differs, a 409 Conflict is returned.

Idempotency keys expire after 24 hours.