Skip to main content
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

FieldTypeDescription
typestringError category (see taxonomy below)
codestringMachine-readable error code
messagestringTechnical description for developers
display_messagestringUser-safe message suitable for end users
paramstring | nullThe parameter that caused the error, if applicable
doc_urlstringLink to documentation for this specific error
suggested_actionstringWhat 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.
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."
}
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."
}
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.
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."
}
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."
}
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."
}
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.
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.
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).
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.
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."
}
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)
  }
}