Error Codes

Understanding and handling API error responses.

Error Response Format

When an error occurs, the API returns a JSON response with the following structure:

{
  "success": false,
  "message": "Human-readable error message",
  "errors": {
    "field_name": ["Validation error message"]
  }
}

The HTTP status code indicates the type of error that occurred.

HTTP Status Codes

200

OK

The request was successful.

{
  "success": true,
  "data": {
    "result": "Success data here"
  },
  "metadata": {
    "actions_consumed": 1
  }
}

401

Unauthorized

Authentication failed. Your API token is missing or invalid.

Common Causes:

Missing Authorization header
Invalid or expired API token
Incorrect token format (should be Bearer YOUR_TOKEN)

Solution:

Verify your API token is correct and included in the Authorization header. Create a new token if needed.

{
  "success": false,
  "message": "Unauthenticated."
}

402

Payment Required

Your organization has insufficient actions remaining in the monthly pool.

Common Causes:

Monthly action pool depleted
Plan downgraded mid-month
High usage spike

Solution:

Upgrade your plan or wait until your monthly pool resets. Check your usage dashboard for details.

{
  "success": false,
  "message": "Insufficient actions remaining. You have 0 actions left."
}

404

Not Found

The requested tool or resource does not exist.

Common Causes:

Incorrect tool type in URL
Typo in endpoint path
Tool has been deprecated or removed

Solution:

Check the API Reference for the correct tool type and endpoint.

{
  "success": false,
  "message": "Tool not found."
}

422

Unprocessable Entity

The request data failed validation.

Common Causes:

Missing required parameters
Invalid parameter types or formats
Parameter values out of acceptable range

Solution:

Review the errors object in the response to see which fields failed validation and why.

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "url": ["The url field is required."],
    "method": ["The selected method is invalid."]
  }
}

429

Too Many Requests

You've exceeded the rate limit for your plan.

Common Causes:

Sending requests too quickly
Parallel requests exceeding limit
No delay between retry attempts

Solution:

Check the Retry-After header in the response to know when you can retry. Implement exponential backoff for retries.

{
  "success": false,
  "message": "Too Many Requests"
}

500

Internal Server Error

An unexpected error occurred on our servers.

What to Do:

Retry the request after a short delay
If the error persists, contact support
Include the request details and timestamp when reporting

{
  "success": false,
  "message": "Server Error"
}

Error Handling Best Practices

Always check the success field
Every response includes a success boolean field. Check this before processing the data.

Implement retry logic with exponential backoff
For transient errors (500, 429), retry with increasing delays: 1s, 2s, 4s, 8s, etc.

Log error details for debugging
Log the full error response, including status code, message, and any validation errors.

Example: Error Handling in JavaScript

async function callAPI() {
  try {
    const response = await fetch('https://api.nisastack.com/api/...', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ /* ... */ })
    });

    const data = await response.json();

    if (!data.success) {
      // Handle API error
      console.error('API Error:', data.message);
      if (data.errors) {
        console.error('Validation Errors:', data.errors);
      }
      return;
    }

    // Process successful response
    console.log('Success:', data.data);

  } catch (error) {
    // Handle network or parsing errors
    console.error('Request failed:', error);
  }
}

Next Steps

Now that you understand error handling, explore the available tools:

Browse API Reference