Error Handling

Understand API error responses and how to handle them gracefully.

Error Format

When an API request fails, Nur returns a consistent JSON error response with an appropriate HTTP status code. Every error response includes a code and a human-readable message. Some errors also include a details object with additional context.

{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'voice_id' parameter is not a valid voice identifier.",
    "details": {
      "parameter": "voice_id",
      "value": "invalid_id_123",
      "expected": "A valid voice ID starting with 'v_' or a preset voice name"
    }
  }
}

HTTP Status Codes

The API uses standard HTTP status codes to indicate the outcome of a request. Codes in the 4xx range indicate client errors, while 5xx codes indicate server-side issues.

Status	Name	Description	Common Causes
400	Bad Request	The request body or parameters are malformed.	Invalid JSON, missing required fields, wrong data types
401	Unauthorized	Authentication is missing or invalid.	Missing API key, expired key, malformed Authorization header
403	Forbidden	The API key lacks required permissions.	Insufficient key scopes, accessing another account's resources
404	Not Found	The requested resource does not exist.	Invalid voice ID, deleted resource, wrong endpoint URL
409	Conflict	The request conflicts with current state.	Duplicate resource creation, concurrent modification
413	Payload Too Large	The request body exceeds the size limit.	Audio file too large, text input exceeds character limit
422	Unprocessable Entity	The request is well-formed but semantically invalid.	Unsupported audio format, invalid language code, incompatible options
429	Rate Limited	Too many requests in a given time window.	Exceeded per-minute request limit, exceeded monthly quota
500	Server Error	An unexpected error occurred on the server.	Internal bug, infrastructure failure, temporary outage
503	Service Unavailable	The service is temporarily unavailable.	Planned maintenance, capacity limits, dependency outage

Error Codes

In addition to HTTP status codes, each error response includes a specific error.code string that you can use for programmatic error handling.

Code	HTTP Status	Description
invalid_api_key	401	The provided API key is invalid, expired, or has been revoked.
missing_parameter	400	A required parameter is missing from the request.
invalid_parameter	400	A parameter value is invalid or out of the accepted range.
file_too_large	413	The uploaded file exceeds the maximum allowed size.
unsupported_format	422	The provided file format is not supported for this operation.
voice_not_found	404	The specified voice ID does not exist or is not accessible.
rate_limit_exceeded	429	The request rate limit or monthly quota has been exceeded.
insufficient_credits	403	Your account does not have enough credits for this operation.
service_unavailable	503	The service is temporarily unavailable. Retry after a short delay.

Handling Errors

The Nur SDKs throw typed error classes that you can catch and handle based on the error type. Always wrap API calls in error handling to provide a graceful experience.

from nur import NurClient, NurError, RateLimitError
from nur import ValidationError, AuthenticationError, NotFoundError
client = NurClient()
try:
    audio = client.tts.generate(
        text="Hello world",
        voice_id="rachel_v2",
    )
    audio.save("output.mp3")
except AuthenticationError as e:
    # 401 - Invalid or missing API key
    print(f"Auth failed: {e.message}")
except NotFoundError as e:
    # 404 - Resource not found
    print(f"Not found: {e.message}")
except ValidationError as e:
    # 400/422 - Invalid parameters
    print(f"Validation error: {e.message}")
    if e.details:
        print(f"Parameter: {e.details.get('parameter')}")
except RateLimitError as e:
    # 429 - Rate limited
    print(f"Rate limited. Retry after {e.retry_after}s")
except NurError as e:
    # Catch-all for any other API error
    print(f"API error {e.status_code}: {e.code} - {e.message}")

Retry Strategy

Not all errors should be retried. Understanding which errors are transient helps you build a robust integration.

Retryable Errors

429 Rate Limited - retry after the Retry-After delay
500 Server Error - retry with exponential backoff
503 Service Unavailable - retry with exponential backoff

Non-Retryable Errors

400 Bad Request - fix the request parameters
401 Unauthorized - check your API key
403 Forbidden - check key scopes or credits
404 Not Found - verify the resource exists

import time
from nur import NurClient, NurError, RateLimitError
client = NurClient()
def call_with_retry(fn, max_retries=5):
    """Call a function with exponential backoff on retryable errors."""
    for attempt in range(max_retries):
        try:
            return fn()
        except RateLimitError as e:
            # Use the server-provided Retry-After value
            wait = e.retry_after or (2 ** attempt)
            print(f"Rate limited. Waiting {wait}s...")
            time.sleep(wait)
        except NurError as e:
            if e.status_code in (500, 503):
                wait = min(2 ** attempt, 60)
                print(f"Server error {e.status_code}. Retrying in {wait}s...")
                time.sleep(wait)
            else:
                raise  # Non-retryable error
    raise Exception("Max retries exceeded")
# Usage
audio = call_with_retry(
    lambda: client.tts.generate(text="Hello", voice_id="rachel_v2")
)

Rate Limit Headers

Every API response includes rate limit headers so you can proactively manage your request rate before hitting the limit.

X-RateLimit-Limit: 1000        # Max requests per minute for your tier
X-RateLimit-Remaining: 847     # Requests remaining in current window
X-RateLimit-Reset: 1706108400  # Unix timestamp when the window resets
Retry-After: 12                # Seconds to wait (only on 429 responses)

Tip: Proactive Rate Limiting

Monitor the X-RateLimit-Remaining header and slow down your requests when approaching zero. This is more efficient than waiting for a 429 response and retrying.