Error Handling & Troubleshooting

Triage steps, retry strategy, and links to the full error-code reference.

Looking for the Gonka API hub? Start here.

API Reference

Use the API reference for the definitive error codes and examples:

• Error codes list — status codes, causes, and resolution steps.
• Error handling examples — ready-to-use patterns for retries and fallbacks.
• Low balance warning header — surface warnings before requests start failing.

Triage Checklist

Capture these details before retrying or escalating:

• HTTP status and error code
• Request ID or trace details from response headers
• Request payload (redact secrets) and model ID
• Whether the error is user-facing or background

Retry Strategy

Retry only when it's safe, and respect Retry-After.

• Retry 429/503/504 with exponential backoff
• Do not retry 401/402/403 without user action
• Use idempotency keys for background jobs