Errors

Status: The minimal durable-task HTTP boundary is available in the production partner preview. Error variants belonging only to turn mode or reserved request overrides remain contract-only.

There are two different failure lanes:

Request failures return a non-2xx response with RFC 9457-style application/problem+json when a problem body is available.
Accepted durable runs report execution failure through GET /v1/runs/:id and a terminal run.failed SSE event. A durable failure is not a turn-style request.failed event.

Candidate offline turn schemas define terminal request.failed events and tool-call identifiers. They are unserved: mode: "turn" returns 400 invalid_request, and /v1/chat is not routed. Do not build a durable task integration around those fields.

HTTP problem object

Field	Type	Required	Description
`type`	URL string	Yes	URI identifying the problem type.
`title`	string	Yes	Short human-readable summary.
`status`	integer 400–599	Yes	HTTP status code repeated in the body.
`detail`	string	No	Explanation for this occurrence.
`instance`	string	No	Occurrence identifier.
`code`	string	Yes	Machine-readable problem code.
`requestId`	string	No	Correlation identifier when one is available.
`retryable`	boolean	Yes	Authoritative retry signal for this response.
`retryAfterMs`	integer ≥ 0	No	Server-requested delay when retryable.
`fieldErrors`	object[]	No	Field-level validation details.

The reference client parses the body best-effort. If a non-2xx response has no valid problem body, it reports AI platform request failed (<status>) with a null problem. Never assume a proxy or upstream failure includes JSON.

Common public HTTP codes

`code`	Meaning	What to do
`authentication_failed`	Bearer key is missing, malformed, revoked, or invalid.	Fix credentials; do not retry unchanged.
`authorization_failed`	The key lacks authority or the resource is outside its tenant.	Fix scopes/tenant context; do not retry unchanged.
`entitlement_failed`	The tenant is not admitted to the operation.	Change entitlement or contact Praxa.
`rate_limited`	An applicable limit was exceeded.	Honor `Retry-After` or `retryAfterMs` when supplied.
`invalid_request`	Strict request validation failed.	Correct the request, using `fieldErrors` when present.
`conflict`	State changed, an approval digest is stale, or an idempotency key was reused with different normalized input.	Re-read state; never retry blindly.
`internal_failed`	Unexpected server failure.	Retry only when `retryable` is true.

The shared source SDK also reserves provider, tool, memory, approval-timeout, and turn-stream error codes. Their presence in the enum does not mean the current minimal task projector emits corresponding rich tool or turn events.

Durable run failures

Ordinary durable failures project as failure.code: "run_failed". If Praxa cannot verify whether a committing action happened during cancellation reconciliation, the deployed and canary-proved refinement projects this terminal failure:

{
  "apiVersion": "v1",
  "run_id": "2f47a86e-72ce-4f27-8ff0-7dc0c959fd35",
  "sequence": 44,
  "at": "2026-07-31T12:00:05.000Z",
  "type": "run.failed",
  "failure": {
    "code": "run_outcome_unknown",
    "message": "A committing action may have happened, but the final outcome could not be verified. Do not retry automatically.",
    "retryable": false
  }
}

Separate production canaries proved the pre-dispatch and provider-in-flight final-state branches. When you receive this result, reconcile the external system before submitting any replacement work.

Example HTTP failure

curl -i https://api.praxa.io/v1/execute \
  -X POST \
  -H "Authorization: Bearer praxa_sk_bad_key" \
  -H "Content-Type: application/json" \
  -d '{}'

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://api.praxa.io/problems/authentication_failed",
  "title": "Authentication failed",
  "status": 401,
  "code": "authentication_failed",
  "retryable": false
}

TypeScript

import { AiPlatformHttpError } from "@nexislabs/ai-platform";

try {
  await client.getRun(runId);
} catch (error) {
  if (error instanceof AiPlatformHttpError) {
    console.error(error.status, error.problem?.code, error.problem?.detail);
    if (error.problem?.retryable) {
      // Back off by error.problem.retryAfterMs when present, then retry.
    }
  }
}

The package is source-available in the Praxa repository; it is not yet published to npm.

API reference

Keys & access

Approvals & policy

Studio & workflows

Security

SDK

How-to

Enterprise

Reference

HTTP problem object

Common public HTTP codes

Durable run failures

Example HTTP failure

TypeScript

​HTTP problem object

​Common public HTTP codes

​Durable run failures

​Example HTTP failure

​TypeScript

HTTP problem object

Common public HTTP codes

Durable run failures

Example HTTP failure

TypeScript