Errors and error codes

How Hyperbolic signals failure: HTTP status codes, canonical error codes, and retry guidance.

Errors and error codes#

Every Hyperbolic API response uses a uniform envelope:

// success
{ "ok": true, "data": { /* ... */ } }
 
// failure
{ "ok": false, "error": { "code": "VALIDATION_ERROR", "message": "..." } }

The TypeScript SDK classifies errors into a small set of PairError codes that you can branch on without parsing HTTP status:

NETWORKPairErrorCodeoptional

The request could not reach the server — likely a DNS, TLS or connectivity issue. Safe to retry.

TIMEOUTPairErrorCodeoptional

The request exceeded the client timeout (default 15s). Safe to retry with backoff.

AUTHPairErrorCodeoptional

HTTP 401 or 403, or an UNAUTHORIZED / FORBIDDEN error code. Get a new agent token and retry.

VALIDATIONPairErrorCodeoptional

HTTP 400/404/409/422, or a VALIDATION_ERROR / NOT_FOUND / CONFLICT error code. Do not retry the same payload.

SERVERPairErrorCodeoptional

HTTP 5xx. Safe to retry with backoff.

UNKNOWNPairErrorCodeoptional

Anything else.

Common server error codes#

| Code | HTTP | Meaning | |------|------|---------| | VALIDATION_ERROR | 400 | Request body or parameters failed schema validation | | UNAUTHORIZED | 401 | Missing or invalid Authorization: Bearer token | | FORBIDDEN | 403 | Token is valid but not authorized for this resource | | NOT_FOUND | 404 | Session, note, file, agent, etc. does not exist | | CONFLICT | 409 | Optimistic lock failure (see notes) or state conflict | | RATE_LIMITED | 429 | Rate limit hit — back off and retry | | INTERNAL_ERROR | 500 | Server bug; report to support |

The SDK automatically retries network errors and timeouts once after a 2-second delay. All other errors are returned to your code immediately.

Session preview

TypeScript SDK