> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API troubleshooting

> Diagnose Telnyx REST API authentication, authorization, validation, throttling, and transient service failures.

Start with a minimal read-only request so product provisioning and side effects do not obscure transport or authentication failures:

```bash theme={null}
curl --request GET \
  --url "https://api.telnyx.com/v2/balance" \
  --header "Authorization: Bearer $TELNYX_API_KEY" \
  --header "Accept: application/json" \
  --verbose
```

Redact the `Authorization` header before sharing command output.

## Diagnostic sequence

1. Confirm the request uses `https://api.telnyx.com/v2` and the method/path from the API reference.
2. Confirm the header is exactly `Authorization: Bearer <key>`.
3. Confirm that the environment variable exists in the current process, then confirm the key has not expired or been revoked and belongs to the expected account.
4. Record the HTTP status, Telnyx error `code`, `title`, `detail`, and `source` fields.
5. Compare the request with the endpoint schema, including media type, required fields, formats, and query parameters.
6. Check account level, balance, resource ownership, and product provisioning when authorization fails.
7. Apply rate-limit or retry handling only after classifying the failure.

## Common failures

### 401 Unauthorized

Check for a missing Bearer header, truncated or invalid key, revoked key, or an environment variable that was not loaded by the current shell or process. Inspect only whether the variable is present—do not print its secret value. Create or rotate the key only after separating a local environment-loading failure from an API credential failure, then repeat the read-only balance request.

### 403 Forbidden

Authentication succeeded, but the operation is not permitted. Check resource ownership, account verification, product capability requirements, provisioning, and restrictions shown in Mission Control Portal. Do not repeatedly retry a `403` without changing the access condition.

### 404 Not Found

Confirm the API version, path, and resource identifier. A resource belonging to another account can also be unavailable to the current credential.

### 400 or 422 validation failure

Read every member of the `errors` array. Use `source.pointer` for a request-body field and `source.parameter` for a query parameter. Correct the request before retrying.

### 429 Too Many Requests

Stop requests in the affected scope and follow [API rate limiting](/docs/development/api-fundamentals/reliability/rate-limiting). Honor `Retry-After` when present.

### 5xx or network failure

Check [Telnyx Status](https://status.telnyx.com) and preserve request context. Retry only when the operation is safe according to [API retries and reliability](/docs/development/api-fundamentals/reliability/command-retries). A timed-out mutating request can still have completed.

## Correct common curl mistakes

### Missing `Bearer` scheme

Incorrect:

```bash theme={null}
curl --request GET \
  --url "https://api.telnyx.com/v2/balance" \
  --header "Authorization: $TELNYX_API_KEY"
```

Correct:

```bash theme={null}
curl --request GET \
  --url "https://api.telnyx.com/v2/balance" \
  --header "Authorization: Bearer $TELNYX_API_KEY"
```

### Query strings with square-bracket parameters

Quote URLs containing `&` so the shell does not split the command. Also disable curl URL globbing when parameter names contain square brackets.

Incorrect:

```bash theme={null}
curl --request GET \
  --url https://api.telnyx.com/v2/available_phone_numbers?filter[country_code]=US&filter[locality]=Chicago \
  --header "Authorization: Bearer $TELNYX_API_KEY"
```

Correct:

```bash theme={null}
curl --globoff --request GET \
  --url "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code]=US&filter[locality]=Chicago" \
  --header "Authorization: Bearer $TELNYX_API_KEY"
```

Percent-encoding the brackets as `%5B` and `%5D` is equivalent to using `--globoff`.

## Collect support evidence

Provide the UTC timestamp, method and path, HTTP status and Telnyx error code, a returned request or correlation identifier when the response supplies one, redacted request and response bodies, product resource identifiers, and reproduction frequency.

Never provide API keys, Bearer headers, webhook signing keys, or unredacted personal data.

## References

* [API error codes](/docs/development/api-fundamentals/api-errors)
* [Requests and responses](/docs/development/api-fundamentals/request-response)
* [Telnyx Support](https://support.telnyx.com)