Error Handling

Complete reference for handling errors from the Nascentist API.

Error Response Format

All errors follow a consistent structure:

{
  "error": {
    "code": "string",
    "message": "string",
    "param": "string (if applicable)",
    "type": "string"
  }
}

Error Codes

Code	Status	Description
invalid_request	400	Missing or invalid parameters
authentication_error	401	Invalid or missing API key
permission_denied	403	API key revoked or insufficient permissions
not_found	404	Resource not found
rate_limit_exceeded	429	Daily or monthly limit reached
internal_error	500	Server-side error
model_unavailable	503	Model temporarily unavailable

Retry Logic

Different errors require different retry strategies:

Rate Limited (429)

Wait until the reset timestamp provided in the response:

// Check for reset_at in response
const resetAt = new Date(error.error.reset_at);
const waitTime = resetAt - new Date();
if (waitTime > 0) {
  await new Promise(r => setTimeout(r, waitTime));
}

Server Errors (500/503)

Use exponential backoff with max 3 retries:

import time

def make_request_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=data)
        
        if response.status_code == 200:
            return response.json()
        elif response.status_code in [500, 503]:
            wait_time = 2 ** attempt  # 1s, 2s, 4s
            print(f"Server error, retrying in {wait_time}s...")
            time.sleep(wait_time)
        else:
            response.raise_for_status()
    
    raise Exception("Max retries exceeded")

Best Practices

• Always check for errors before accessing response data
• Log error codes for debugging
• Implement proper retry logic for transient errors
• Display user-friendly error messages
• Monitor rate limit headers to avoid 429 errors

← Previous Next: Best Practices →