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

# Errors

> Handle Aptranet API status codes, error documents, trace IDs, and retryable failures.

When available, structured errors use this shape:

```json theme={null}
{
  "error_code": "validation_error",
  "error_description": "Some configuration values are invalid.",
  "trace_id": "01JEXAMPLETRACE"
}
```

Some endpoints return `error` instead of `error_code`. Clients should accept either key and should not branch on the human-readable description.

## HTTP status codes

| Status | Meaning | Action |
| - | - | - |
| 400 | Invalid request or missing required context | Fix the request; do not retry unchanged |
| 401 | Missing or invalid authentication | Verify both credential headers |
| 402 | Product or billing state does not permit the operation | Review the active subscription |
| 403 | Disabled key, wrong secret, or insufficient permission | Review the key and its permissions |
| 404 | Route or project resource not found | Verify path and resource ID |
| 409 | Resource state conflicts with the operation | Refresh current state and resolve the conflict |
| 422 | Semantically invalid configuration | Correct the documented fields |
| 429 | Rate limit exceeded | Honor `Retry-After` and back off |
| 500 | Unexpected service failure | Retry cautiously; contact support if persistent |
| 502 / 503 / 504 | Upstream unavailable or timed out | Retry with exponential backoff and jitter |

## Trace IDs

Include `trace_id`, UTC timestamp, method, path, status, project name, and resource ID when contacting support. Never include the secret or full authorization header.

<Tip>
  Log a redacted request summary and trace ID at the integration boundary. This preserves diagnostic value without leaking credentials or full configuration documents.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.