API error codes

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

When the Warp 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, HTTP status, human-readable message, and resolution details.

Response format

All error responses share this structure:

{
  "type": "/factories/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)
infrastructure_timeout — Task terminated after exceeding the maximum allowed runtime
agent_process_failed — Agent process exited unexpectedly during task execution

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.

Warp Platform API — API reference for creating and managing agent tasks
Cloud Agents Overview — How cloud agents work
Access, Billing, and Identity — Plan requirements and billing details