Errors - Developer Platform

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

Error response format

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

Always include the request_id from error responses when contacting support. It helps us trace exactly what happened.

Error taxonomy

`invalid_request_error` (400)

The request was malformed or missing required parameters.

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.

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

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.

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

text_too_long

Cause: The text parameter exceeds the maximum allowed length of 5,000 characters.Fix: Truncate or split long texts before sending.

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

`authentication_error` (401)

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

missing_api_key

Cause: No Authorization header was provided.Fix: Include the header: Authorization: Bearer nawa_live_sk_xxx

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

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).

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

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.

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

revoked_api_key

Cause: The API key has been manually revoked.Fix: Use a different active key or create a new one.

{
  "type": "authentication_error",
  "code": "revoked_api_key",
  "message": "This API key has been revoked.",
  "suggested_action": "Create a new API key from the dashboard."
}

`insufficient_credits` (402)

Your account balance is insufficient for the requested operation.

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.

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

`rate_limit_error` (429)

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

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.

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

sandbox_exhausted

Cause: You’ve used all 100 lifetime requests on your free key.Fix: Buy credits to unlock a live key.

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

`api_error` (500)

An unexpected error occurred on the NAWA side.

internal_error

Cause: An unexpected internal failure.Fix: Retry the request. If the issue persists, contact support with the request_id.

{
  "type": "api_error",
  "code": "internal_error",
  "message": "An unexpected error occurred. Please retry.",
  "suggested_action": "Retry the request. Contact support if the issue persists."
}

provider_failure

Cause: The upstream AI provider (ALLaM) experienced a failure.Fix: Retry after a brief delay. Check status.trynawa.com for incidents.

{
  "type": "api_error",
  "code": "provider_failure",
  "message": "AI provider temporarily unavailable.",
  "suggested_action": "Retry after a few seconds. Check status.trynawa.com for updates."
}

Handling errors in code

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)
  }
}

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}")

​Error response format

​Error object fields

​Error taxonomy

​invalid_request_error (400)

​authentication_error (401)

​insufficient_credits (402)

​rate_limit_error (429)

​api_error (500)

​Handling errors in code

Error response format

Error object fields

Error taxonomy

`invalid_request_error` (400)

`authentication_error` (401)

`insufficient_credits` (402)

`rate_limit_error` (429)

`api_error` (500)

Handling errors in code