Errors

Reference for all error codes returned by the Oz platform API. Each error includes an HTTP status, machine-readable code, and actionable resolution steps.

When the Oz platform API encounters an error, it returns a structured JSON response following RFC 7807 (Problem Details for HTTP APIs). Every error response includes a machine-readable error code, a human-readable message, and metadata to help you diagnose and resolve the issue.

---

Response format

All error responses share this structure:

{
  "type": "https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/invalid-request",
  "title": "The request contains invalid or missing parameters.",
  "status": 400,
  "detail": "schedule_id is required",
  "instance": "/api/v1/agent/tasks",
  "error": "The request contains invalid or missing parameters. (schedule_id is required)",
  "retryable": false,
  "trace_id": "abc123def456..."
}

Error responses use the application/problem+json content type per RFC 7807.

Field reference

• type — A URI identifying the error type. Links to the documentation page for that error.

• title — A short, human-readable summary of the problem.

• status — The HTTP status code for this response.

• detail — Additional context specific to this occurrence of the error. Not always present.

• instance — The request path that produced the error.

• error — A backward-compatible field combining title and detail (for older clients). When detail is present, formatted as "title (detail)".

• retryable — Whether this request can be retried. If true, the platform may automatically retry the operation.

• trace_id — An OpenTelemetry trace ID, included when available. Reference this when contacting support.

Some errors include additional metadata fields (for example, auth_url, provider, or inaccessible_repos). These are documented on each error's page.

---

Error categories

Errors are split into two categories based on what caused the failure:

User errors

These indicate something the caller needs to fix. When a cloud agent task encounters a user error, the task transitions to the FAILED state.

• insufficient_credits — Team has no remaining add-on credits

• feature_not_available — Feature not included in your current plan

• external_authentication_required — External service authorization needed

• not_authorized — Insufficient permissions for the operation

• invalid_request — Malformed request or invalid parameters

• resource_not_found — Referenced resource does not exist

• budget_exceeded — Spending budget limit reached

• integration_disabled — Integration is disabled

• integration_not_configured — Integration setup is incomplete

• operation_not_supported — Operation not supported for this resource or state

• environment_setup_failed — Cloud agent environment failed to initialize

• content_policy_violation — Task flagged by content policy checks

• conflict — Request conflicts with the current resource state (retryable)

Platform errors

These indicate a Warp-side issue. When a cloud agent task encounters a platform error, the task transitions to the ERROR state. Retryable errors are automatically retried before the task is marked as failed.

• authentication_required — Invalid or expired API key

• resource_unavailable — Transient infrastructure issue (retryable)

• internal_error — Unexpected server-side error (retryable)

---

Using the trace_id

When an error response includes a trace_id, you can include it when contacting Warp support to help the team locate the specific request in internal logs. This is especially useful for internal_error and resource_unavailable errors.

---

Related

• Oz Agent API & SDK — API reference for creating and managing agent tasks

• Cloud Agents Overview — How cloud agents work

• Access, Billing, and Identity — Plan requirements and billing details