API Troubleshooting and Support Diagnostics

Use this guide when an API request fails, a client cannot authenticate, a gateway behaves differently than expected, or Support asks for diagnostic details.

For full API reference and examples, use https://api-docs.hatz.ai/. For API triage, see API Troubleshooting. For model IDs, token and usage metadata behavior, and rate-limit interpretation, see Model Compatibility.

Start with the right API surface

Hatz-native chat: use https://ai.hatz.ai/v1/chat/completions for Hatz chat, agents, server-side tools, files, and recursive tool calling.
OpenAI-compatible clients: use https://ai.hatz.ai/v1/openai as the client base URL, or call /v1/openai/responses directly. See OpenAI Responses.
Anthropic-compatible clients: use https://ai.hatz.ai/v1/anthropic as the client base URL, or call /v1/anthropic/messages directly. See Anthropic Messages.
Workflow runs: use POST /v1/workflows/run, then poll GET /v1/workflows/{job_id}. Workflow runs are asynchronous.

Authentication

Use X-API-Key for Hatz REST endpoints.
The OpenAI-compatible and Anthropic-compatible endpoints also accept Authorization: Bearer for API keys because many third-party clients only support Bearer auth.
Do not send API keys in query strings, request bodies, Basic auth, screenshots, or support messages.
API keys inherit the user and tenant permissions of the key owner. If a key works for one endpoint but not another, check user role, tenant access, package, model, app, workflow, and usage permissions.

Request IDs

Hatz API responses include an X-Request-ID header. You can also send your own X-Request-ID header, and Hatz will use that value for the request. If you send your own request ID, use a short opaque value and do not include emails, tenant names, prompts, secrets, customer records, or other sensitive data. Include the response X-Request-ID, timestamp, route, and sanitized error in Support tickets.

Common error classes

401: missing, expired, or invalid authentication. Check the header type and gateway base URL.
403: authenticated but not allowed. Check role, tenant, MSP/customer scope, and feature permissions.
404: resource not found or not visible to the API key owner. Check IDs, tenant scope, and sharing.
422: request shape failed validation. Compare the body to the API reference and remove unsupported fields.
429: credit, model, package, role, tenant, concurrency, or provider-side limit. Include model, endpoint, tenant/user context, and request ID.
5xx: server, provider, or transient infrastructure failure. Retry once if safe, then contact Support with diagnostics.

What to send Support

Endpoint and full base URL used.
Auth method used, without the secret value.
X-Request-ID response header.
Timestamp and timezone.
Affected tenant, workspace, organization, API key owner, or user scope if it is safe and relevant to share.
HTTP status code and sanitized error body.
SDK, IDE, automation tool, or third-party client name and version.
Model ID or alias sent, whether streaming was enabled, and whether files, tools, workflows, images, cache usage metadata, or large context were involved.
For workflow or file API issues, include the visible job_id, workflow step_id when returned by the API, or file_id when available.
Expected behavior, actual behavior, minimal sanitized reproduction, business impact, urgency, and workaround.

For API issues, use the response X-Request-ID. For product UI issues, share visible item, run, chat, or generated-file links, timestamps, screenshots, and error text instead of trying to find hidden internal IDs.

Never send these in a ticket

Raw API keys, bearer tokens, or private secrets.
Complete sensitive prompts, customer records, private files, or unredacted logs.
Screenshots that reveal tokens, credentials, private tenant data, or customer data unrelated to the issue.