Error Handling

HASP uses one stable set of error codes across the AI API and the App Builder SDK. The two identifiers to branch on are the HTTP status code and error.code — error.message is human-readable and may change without notice.

The error envelope

Every error shares the same shape:

{
  "success": false,
  "error": {
    "code": "PHI_BLOCKED",
    "type": "forbidden",
    "message": "Message contains PHI that cannot be sent without redaction.",
    "retryable": false,
    "request_id": "req_01JQREQ000000000000000000"
  },
  "meta": {
    "request_id": "req_01JQREQ000000000000000000"
  }
}

Always log request_id — it is the key for support and for retrieving the corresponding audit record.

Error categories

The codes fall into five categories. Each maps to an HTTP status range and a clear handling rule:

Category	Typical status	What it means	What to do
Authentication	`401`	The API key is missing, malformed, or revoked (`INVALID_API_KEY`).	Fix the credential. Not retryable.
Authorization & scope	`403`	The key lacks a required scope (`MISSING_SCOPE`), or a feature is not enabled for the org.	Grant the scope or enable the feature. Not retryable.
Compliance / PHI	`402`, `403`	No active BAA (`BAA_REQUIRED`), PHI blocked by policy (`PHI_BLOCKED`), PHI in a tool schema (`PHI_IN_TOOL_SCHEMA`), or credits exhausted (`AI_CREDITS_EXHAUSTED`).	Sign the BAA, adjust PHI mode, or top up credits. Generally not retryable until the underlying condition changes.
Validation	`400`, `422`	The request body failed validation (`VALIDATION_FAILED`) or an input was unprocessable. `error.param` names the offending field.	Fix the request. Not retryable as-is.
Rate limit & budget	`429`	RPM/daily limit hit (`RATE_LIMITED`) or a spend cap reached (`BUDGET_EXCEEDED`).	Honor `Retry-After` and back off. Retryable. See Rate Limits.
Server / upstream	`500`, `502`, `503`	An internal error (`INTERNAL_ERROR`), an upstream provider failure (`INFERENCE_UPSTREAM_FAILURE`), or a temporarily unavailable gateway (`INFERENCE_UNAVAILABLE`).	Retry with exponential backoff. Retryable.

Retry guidance

The error.retryable boolean tells you whether a retry can ever succeed without changing the request:

Retry 429 and 5xx errors. Prefer error.details.retry_after_seconds (or the Retry-After header) when present; otherwise use exponential backoff with a ceiling.
Do not retry 400, 401, 403, and 422 — they require a change to the request, the credential, or the org’s configuration. Retrying an identical request will fail identically.

Streaming responses deliver errors that occur after the stream opens as SSE error events rather than HTTP status codes — handle both paths.

Full reference

This page is the platform-level overview. The complete code table — every code, its exact HTTP status, the error.details fields it carries, and a worked retry loop — lives in the AI API error reference:

AI API Error Reference

The authoritative, exhaustive list of error codes and handling patterns, including streaming errors.

AI Studio

Platform

AI API

App Builder SDK

Error Handling

The error envelope

Error categories

Retry guidance

Full reference

AI API Error Reference

​The error envelope

​Error categories

​Retry guidance

​Full reference

AI API Error Reference

The error envelope

Error categories

Retry guidance

Full reference