Operations · 2026-09-01 · HippoAPI Documentation Team

Errors and retries

Classify API failures, capture useful evidence, and retry only transient requests that are safe to repeat.

Error response shape

Non-2xx responses use an error object with a human-readable message and may include a type, code, or request ID. Treat the HTTP status as the first classification signal and preserve the request ID when present.

{
  "error": {
    "message": "Error description (request id: ...)",
    "type": "new_api_error",
    "code": ""
  }
}

Status codes and actions

Status	Meaning	Application action
400	Invalid request, model, field, or unsupported parameter.	Fix the request. Do not retry the same body unchanged.
401	API key missing, malformed, expired, disabled, or invalid.	Correct or rotate the key. Do not retry automatically.
403	The account, key, IP, group, or model is not allowed.	Review access controls and model availability.
402	Balance or quota is insufficient.	Review Wallet and key quota before sending more requests.
404	Endpoint or model resource not found.	Check the base URL, endpoint path, and exact model identifier.
429	Current request rate or concurrency is too high.	Back off with jitter and reduce concurrency.
5xx	Platform or upstream provider failure.	Retry safe requests with a strict attempt limit; preserve the request ID.

Use bounded exponential backoff

Retry only errors likely to be transient: connection failures, HTTP 429, and selected 5xx responses. Add random jitter so many workers do not retry at the same moment. Set both a maximum attempt count and an overall deadline.

const delaysMs = [500, 1000, 2000]

for (let attempt = 0; attempt <= delaysMs.length; attempt++) {
  try {
    return await callHippoAPI()
  } catch (error) {
    const status = error?.status
    const retryable = status === 429 || (status >= 500 && status < 600)
    if (!retryable || attempt === delaysMs.length) throw error
    const jitter = Math.floor(Math.random() * 250)
    await new Promise((resolve) => setTimeout(resolve, delaysMs[attempt] + jitter))
  }
}

Log evidence without logging secrets

Do not log Authorization headers, full API keys, or complete prompts containing personal, confidential, or regulated data. Redact before forwarding errors to observability tools.

UTC timestamp and application trace ID.
HippoAPI request ID when present.
HTTP method and endpoint path.
Model identifier, status code, duration, and retry attempt.
A redacted error summary.

Before contacting support

Reproduce the issue with the smallest safe request, confirm the model appears in GET /v1/models, and check Usage Logs. Then provide the timestamp, endpoint, model, HTTP status, request ID, and a redacted request summary to [email protected].

Do not include your API key. If you already shared or exposed it, revoke it before continuing the investigation.