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

# Errors

> Public API error envelope and client handling rules.

AlphaEngine public errors use problem details.

<CardGroup cols={2}>
  <Card title="Typed handling" icon="braces">
    Clients branch on HTTP status, `code`, and `fieldErrors`, not free-form
    strings.
  </Card>

  <Card title="Traceable failures" icon="fingerprint">
    `requestId` stays with the failure so beta users and operators can debug
    the same event.
  </Card>
</CardGroup>

## Error envelope

Errors use:

```http theme={null}
content-type: application/problem+json
```

Base fields:

<AccordionGroup>
  <Accordion title="Problem details base fields">
    `type`, `title`, `status`, `detail`, and `instance` when useful.
  </Accordion>

  <Accordion title="AlphaEngine extensions">
    `code`, `family`, `requestId`, and `fieldErrors` when relevant.
  </Accordion>
</AccordionGroup>

## Validation failures

Public request bodies are strict in v1 unless a field is explicitly modeled as
an open record.

Unsupported top-level or nested request fields return `400` with:

<Callout>
  Validation failures use `code = REQUEST_VALIDATION_FAILED`.
</Callout>

Use `fieldErrors` to point users to invalid or unsupported fields.

## Client rule

Clients should never parse arbitrary strings for control flow.

<CardGroup cols={2}>
  <Card title="Status" icon="server">
    Use the HTTP status class for broad handling.
  </Card>

  <Card title="Code" icon="braces">
    Use `code` for stable AlphaEngine-specific branching.
  </Card>

  <Card title="Field errors" icon="list-x">
    Use `fieldErrors` to highlight invalid request fields.
  </Card>

  <Card title="Request id" icon="fingerprint">
    Keep `requestId` in client logs and support messages.
  </Card>
</CardGroup>

## Common statuses

<AccordionGroup>
  <Accordion title="400 request validation failed">
    The request shape, field value, or unsupported property violated the public
    v1 contract.
  </Accordion>

  <Accordion title="401 missing or invalid API key">
    The request did not include a usable `x-api-key` value.
  </Accordion>

  <Accordion title="403 inactive key or insufficient scope">
    The key exists but is inactive or does not carry the scope required for the
    route.
  </Accordion>

  <Accordion title="429 compute or concurrency limit rejected">
    The key exceeded its compute-unit budget or in-flight request cap.
  </Accordion>

  <Accordion title="503 auth or upstream unavailable">
    Auth resolution or an upstream service could not complete the request.
  </Accordion>
</AccordionGroup>

## Related pages

<CardGroup cols={2}>
  <Card title="Authentication" icon="key-round" href="/api/authentication">
    Scopes, compute budget, and rate-limit behavior.
  </Card>

  <Card title="API overview" icon="file-check" href="/api/overview">
    The implemented public route surface.
  </Card>
</CardGroup>