Errors - Aptranet Developers

When available, structured errors use this shape:

{
  "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.

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