Errors

Generic malformed request. Typical causes: body is not valid JSON, the Content-Type header is missing or wrong, conflicting query parameters were sent (e.g. both limit and a contradictory pagination flag), or a path parameter is malformed (non-UUID in a UUID slot).

Verify the body parses as JSON (echo $body | jq . is a quick sanity check), confirm the Content-Type: application/json header is set, and double-check the path / query parameters against the API reference. Once you fix the payload, retry.

{
  "error": "Invalid JSON body",
  "code": "bad_request",
  "request_id": "0cf409f7-382a-4c24-be9f-ae1192c38619",
  "detail": "Invalid JSON body"
}

The request body exceeded the per-route size limit. Most common on transcription endpoints when uploading audio inline (POST /transcribe) past ~10MB. Inline uploads are capped by design; large audio belongs on the presigned-upload path.

For audio larger than ~10MB, use the presigned upload flow: POST /uploads/presign to get a signed upload URL, PUT the bytes directly to that URL, then call POST /transcribe/by-upload with the returned upload_id. This is documented under Transcription.

{
  "error": "Request body too large",
  "code": "payload_too_large",
  "request_id": "0cf409f7-382a-4c24-be9f-ae1192c38619",
  "detail": "Request body too large"
}

A request body field or query parameter failed schema validation. The detail field is an array of per-field error objects (not a single string), so you can map each entry back to the exact JSON path that failed. Common triggers: missing required field, wrong type (string where int expected), string below the minimum length, value not in an allowed enum, malformed UUID / phone number / URL.

For each entry in the detail array: loc is the JSON path of the bad field (["body", "voice_id"]), msg is the human-readable reason, and type is the validation rule that fired (missing, string_too_short, string_pattern_mismatch, etc.). Fix every entry, then retry; partial fixes will still 422 on the remaining ones.

{
  "error": "Validation failed",
  "code": "validation_error",
  "request_id": "3fddfe81-53f3-4ca1-9cea-f5fbc73ce5a2",
  "detail": [
    {
      "loc": ["body", "voice_id"],
      "msg": "Field required",
      "type": "missing"
    },
    {
      "loc": ["body", "system_prompt"],
      "msg": "String should have at least 1 character",
      "type": "string_too_short"
    }
  ],
  "fields": [
    {
      "loc": ["body", "voice_id"],
      "msg": "Field required",
      "type": "missing"
    },
    {
      "loc": ["body", "system_prompt"],
      "msg": "String should have at least 1 character",
      "type": "string_too_short"
    }
  ]
}

The path resource (agent, call, voice, phone number, etc.) does not exist on your account. Note: cross-account access also returns 404 (not 403) to prevent ID enumeration. So a 404 means either the resource genuinely does not exist, or it exists but belongs to a different account.

Verify the ID by listing resources first (GET /agents etc.) to confirm it appears on your account. If you just created the resource, give it a beat to commit; the POST response is the canonical source of truth for the new ID. Safe to retry once you confirm the right ID.

{
  "error": "Agent 'd53208ef-2f34-4be2-8bea-35cd55b399ac' not found",
  "code": "not_found",
  "request_id": "0cf409f7-382a-4c24-be9f-ae1192c38619",
  "detail": "Agent 'd53208ef-2f34-4be2-8bea-35cd55b399ac' not found"
}

The resource is in a state that conflicts with the requested action. Concrete cases: ending a WebRTC session that already ended ("Session is not active"), idempotency-key reuse with a different request body (Stripe-style protection against double-charge bugs), or a uniqueness violation on registration (e.g. registering the same phone number twice).

Inspect the current state via the matching GET endpoint before retrying. For idempotency conflicts, generate a fresh key per logical operation. For uniqueness conflicts, look up the existing resource and decide whether to update it instead of recreating it. Not safe to blind-retry.

{
  "error": "Session is not active. The pipeline may have already ended.",
  "code": "conflict",
  "request_id": "0cf409f7-382a-4c24-be9f-ae1192c38619",
  "detail": "Session is not active. The pipeline may have already ended."
}

Your credit balance reached zero, the account is in dunning after a failed renewal charge, or the card was declined so many times it is locked. Credits are prepaid: at zero the account is hard-blocked on the spot, and nothing accrues as debt. Affects metered routes only: voice call placement, WebRTC sessions, TTS, transcription. Read routes (agents, usage, conversations) keep working so you can investigate without flying blind. The top-level code is a billing slug such as billing.no_credits or billing.payg_card_repeatedly_failed (not the generic payment_required), and detail is a structured object {code, message, action_url} — branch on the inner code slug for billing-specific handling.

Visit developers.aethexai.com/dashboard/billing to add or update a payment method, top up credits, or upgrade plans. After Stripe confirms the new payment, metered routes unblock on the next request. See Billing for the full lifecycle.

{
  "error": "Card declined on multiple retry attempts. Update your payment method to resume calls.",
  "code": "billing.payg_card_repeatedly_failed",
  "request_id": "0cf409f7-382a-4c24-be9f-ae1192c38619",
  "detail": {
    "code": "billing.payg_card_repeatedly_failed",
    "message": "Card declined on multiple retry attempts. Update your payment method to resume calls.",
    "action_url": "/dashboard/billing"
  }
}