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

# Errors

> Complete error taxonomy with machine-readable codes, display messages, and resolution guidance.

Every NAWA API error returns a consistent JSON envelope with machine-readable codes and human-friendly guidance.

## Error response format

```json theme={null}
{
  "success": false,
  "result": null,
  "errors": [
    {
      "type": "invalid_request_error",
      "code": "missing_required_param",
      "message": "The 'text' parameter is required.",
      "display_message": "Please provide the comment text to classify.",
      "param": "text",
      "doc_url": "https://developers.trynawa.com/errors#missing_required_param",
      "suggested_action": "Include the 'text' field in your request body."
    }
  ],
  "request_id": "req_abc123def456"
}
```

### Error object fields

| Field              | Type           | Description                                        |
| ------------------ | -------------- | -------------------------------------------------- |
| `type`             | string         | Error category (see taxonomy below)                |
| `code`             | string         | Machine-readable error code                        |
| `message`          | string         | Technical description for developers               |
| `display_message`  | string         | User-safe message suitable for end users           |
| `param`            | string \| null | The parameter that caused the error, if applicable |
| `doc_url`          | string         | Link to documentation for this specific error      |
| `suggested_action` | string         | What to do to fix the error                        |

<Tip>
  Always include the `request_id` from error responses when contacting support. It helps us trace exactly what happened.
</Tip>

***

## Error taxonomy

### `invalid_request_error` (400)

The request was malformed or missing required parameters.

<AccordionGroup>
  <Accordion title="missing_required_param">
    **Cause:** A required parameter is missing from the request body.

    **Common triggers:**

    * Missing `text` field in `/v1/classify`
    * Missing `comment_id` in `/v1/comments/:id/reply`

    **Fix:** Check the API reference for required parameters and include them all.

    ```json theme={null}
    {
      "type": "invalid_request_error",
      "code": "missing_required_param",
      "message": "The 'text' parameter is required.",
      "param": "text",
      "suggested_action": "Include the 'text' field in your request body."
    }
    ```
  </Accordion>

  <Accordion title="invalid_param_value">
    **Cause:** A parameter has an invalid value or type.

    **Common triggers:**

    * `platform` not one of: `youtube`, `instagram`, `twitter`, `facebook`
    * `text` is empty or not a string

    **Fix:** Verify parameter values match the expected types and allowed values.

    ```json theme={null}
    {
      "type": "invalid_request_error",
      "code": "invalid_param_value",
      "message": "Invalid value for 'platform'. Must be one of: youtube, instagram, twitter, facebook.",
      "param": "platform",
      "suggested_action": "Use a valid platform value."
    }
    ```
  </Accordion>

  <Accordion title="text_too_long">
    **Cause:** The `text` parameter exceeds the maximum allowed length of 5,000 characters.

    **Fix:** Truncate or split long texts before sending.

    ```json theme={null}
    {
      "type": "invalid_request_error",
      "code": "text_too_long",
      "message": "Text exceeds maximum length of 5000 characters (received 7234).",
      "param": "text",
      "suggested_action": "Shorten the text to 5000 characters or fewer."
    }
    ```
  </Accordion>
</AccordionGroup>

### `authentication_error` (401)

The API key is missing, invalid, expired, or revoked.

<AccordionGroup>
  <Accordion title="missing_api_key">
    **Cause:** No `Authorization` header was provided.

    **Fix:** Include the header: `Authorization: Bearer nawa_live_sk_xxx`

    ```json theme={null}
    {
      "type": "authentication_error",
      "code": "missing_api_key",
      "message": "No API key provided in the Authorization header.",
      "suggested_action": "Add 'Authorization: Bearer YOUR_API_KEY' to your request headers."
    }
    ```
  </Accordion>

  <Accordion title="invalid_api_key">
    **Cause:** The API key is not recognized. It may be malformed or from a different environment.

    **Fix:** Verify the key is correct and matches the environment (free/live).

    ```json theme={null}
    {
      "type": "authentication_error",
      "code": "invalid_api_key",
      "message": "The API key provided is not valid.",
      "suggested_action": "Check that your API key is correct and matches the environment."
    }
    ```
  </Accordion>

  <Accordion title="expired_api_key">
    **Cause:** The free API key has exceeded its 14-day expiry.

    **Fix:** Create a new free key from the dashboard. Live keys don't expire.

    ```json theme={null}
    {
      "type": "authentication_error",
      "code": "expired_api_key",
      "message": "This free API key has expired (14-day limit).",
      "suggested_action": "Create a new free key from the dashboard."
    }
    ```
  </Accordion>

  <Accordion title="revoked_api_key">
    **Cause:** The API key has been manually revoked.

    **Fix:** Use a different active key or create a new one.

    ```json theme={null}
    {
      "type": "authentication_error",
      "code": "revoked_api_key",
      "message": "This API key has been revoked.",
      "suggested_action": "Create a new API key from the dashboard."
    }
    ```
  </Accordion>
</AccordionGroup>

### `insufficient_credits` (402)

Your account balance is insufficient for the requested operation.

<AccordionGroup>
  <Accordion title="balance_exhausted">
    **Cause:** Your credit balance has reached \$0. There is no grace period -- paid endpoints stop immediately.

    **Fix:** Purchase a credit pack from the dashboard to restore access instantly.

    ```json theme={null}
    {
      "type": "insufficient_credits",
      "code": "balance_exhausted",
      "message": "Credit balance exhausted. Purchase credits to continue.",
      "suggested_action": "Buy a credit pack at trynawa.com/developers/keys."
    }
    ```
  </Accordion>
</AccordionGroup>

### `rate_limit_error` (429)

You've exceeded the rate limit for your current tier.

<AccordionGroup>
  <Accordion title="rate_limit_exceeded">
    **Cause:** Too many requests in the current time window.

    **Fix:** Wait until the `X-RateLimit-Reset` time, then retry. Consider upgrading your tier.

    ```json theme={null}
    {
      "type": "rate_limit_error",
      "code": "rate_limit_exceeded",
      "message": "Rate limit exceeded: 120 requests per minute for Growth tier.",
      "suggested_action": "Wait until the rate limit resets or upgrade your tier."
    }
    ```

    The `X-NAWA-RateLimit-Reason` response header provides additional context (`minute_limit` or `sandbox_exhausted`).
  </Accordion>

  <Accordion title="sandbox_exhausted">
    **Cause:** You've used all 100 lifetime requests on your free key.

    **Fix:** Buy credits to unlock a live key.

    ```json theme={null}
    {
      "type": "rate_limit_error",
      "code": "sandbox_exhausted",
      "message": "Free key lifetime limit of 100 requests reached.",
      "suggested_action": "Buy credits to create a live API key at trynawa.com/developers/keys."
    }
    ```
  </Accordion>
</AccordionGroup>

### `api_error` (500)

An unexpected error occurred on the NAWA side.

<AccordionGroup>
  <Accordion title="internal_error">
    **Cause:** An unexpected internal failure.

    **Fix:** Retry the request. If the issue persists, contact support with the `request_id`.

    ```json theme={null}
    {
      "type": "api_error",
      "code": "internal_error",
      "message": "An unexpected error occurred. Please retry.",
      "suggested_action": "Retry the request. Contact support if the issue persists."
    }
    ```
  </Accordion>

  <Accordion title="provider_failure">
    **Cause:** The upstream AI provider (ALLaM) experienced a failure.

    **Fix:** Retry after a brief delay. Check [status.trynawa.com](https://status.trynawa.com) for incidents.

    ```json theme={null}
    {
      "type": "api_error",
      "code": "provider_failure",
      "message": "AI provider temporarily unavailable.",
      "suggested_action": "Retry after a few seconds. Check status.trynawa.com for updates."
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Handling errors in code

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Nawa, NawaAuthError, NawaRateLimitError } from '@nawalabs/sdk'

  const nawa = new Nawa({ apiKey: process.env.NAWA_API_KEY })

  const { data, error } = await nawa.classify({
    text: 'متى الجزء الثاني؟',
    platform: 'youtube'
  })

  if (error) {
    switch (error.type) {
      case 'authentication_error':
        console.error('Check your API key:', error.message)
        break
      case 'rate_limit_error':
        console.log('Rate limited, retrying after:', error.retryAfter)
        break
      case 'insufficient_credits':
        console.error('Buy credits:', error.suggested_action)
        break
      default:
        console.error('API error:', error.message)
    }
  }
  ```

  ```python Python theme={null}
  from nawa import Nawa
  from nawa.errors import NawaAuthError, NawaRateLimitError

  nawa = Nawa(api_key="your_api_key")

  result = nawa.classify(text="متى الجزء الثاني؟", platform="youtube")

  if result.error:
      if result.error.type == "authentication_error":
          print(f"Check your API key: {result.error.message}")
      elif result.error.type == "rate_limit_error":
          print(f"Rate limited, retry after: {result.error.retry_after}")
      elif result.error.type == "insufficient_credits":
          print(f"Buy credits: {result.error.suggested_action}")
      else:
          print(f"API error: {result.error.message}")
  ```
</CodeGroup>