> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/sdks/security-and-errors.md).

# Authentication, retries, and errors

## Authentication

Generated clients support two runtime credentials:

* API key: `X-API-Key: <value>`
* Bearer token: `Authorization: Bearer <value>`

Configure only the mechanism required by the gateway policy. Never embed a credential in the generated package, source repository, mobile application, or browser bundle that cannot protect a secret.

## Scope headers

The published tenant and gateway values are generated as default headers:

* `X-Tenant-ID`
* `X-Gateway-ID`

Client-wide and request-level headers can override defaults. Authentication headers are applied last. Treat scope overrides as privileged configuration.

## Timeout and retry behavior

Every target defaults to a 30-second per-attempt timeout, at most two retries (three total attempts), and exponential delays starting at 200 ms. The exact built-in retry contract is target-specific:

| Target     | Retried failures before the retry limit                                                                                 |
| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| TypeScript | Fetch and per-attempt timeout failures except caller-aborted requests; `408`, `429`, `500`, `502`, `503`, `504`         |
| Python     | `URLError` transport failures; `408`, `429`, `500`, `502`, `503`, `504`                                                 |
| Go         | HTTP request transport failures while the context remains active; `408`, `429`, and every `5xx`                         |
| Java       | `IOException` transport/timeout failures; `408`, `429`, and every `5xx`                                                 |
| C#         | `HttpRequestException` and per-attempt timeout cancellation, but not caller cancellation; `408`, `429`, and every `5xx` |
| PHP        | cURL transport failures reported with status `0`; `408`, `429`, `500`, `502`, `503`, `504`                              |

Built-in retries are not restricted by HTTP method. For non-idempotent business operations, set retries to zero or use an application-level idempotency strategy and overall deadline.

## API errors

Each generated client exposes a language-appropriate API error containing the HTTP status and response body. Handle at least:

| Status | Recommended action                                                  |
| ------ | ------------------------------------------------------------------- |
| 401    | Refresh or replace the credential.                                  |
| 403    | Check consumer, scope, and policy permissions.                      |
| 404    | Verify base URL, route, and path parameters.                        |
| 408    | Respect the application deadline; retry only when safe.             |
| 429    | Apply backoff; the application may inspect and honor `Retry-After`. |
| 5xx    | Correlate the request ID with Kangal telemetry and retry policy.    |

Log request IDs and sanitized error metadata. Do not log authorization headers, API keys, request bodies containing secrets, or unredacted personal data.

Generated clients currently use their built-in exponential retry delay; they do not parse `Retry-After` automatically.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kangal.dev/sdks/security-and-errors.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.