Error Handling

Georender returns structured error responses with actionable information for debugging.

Error Response Format

All errors follow this structure:

{
  "error": "Validation failed",
  "message": "waypoints: At least 2 waypoints required",
  "fields": ["waypoints"],
  "llm_context": {
    "error_code": "VALIDATION_ERROR",
    "summary": "Request validation failed with 1 issue(s)",
    "issues": [
      {
        "field": "waypoints",
        "code": "too_small",
        "message": "At least 2 waypoints required",
        "suggestion": "Add more items to waypoints. Minimum required: 2"
      }
    ],
    "valid_options": {
      "mode": ["route_animation", "region_focus", "multi_route", "country_data"]
    }
  }
}

Error Codes

Authentication Errors (401)

Code	Description	Solution
`AUTHENTICATION_REQUIRED`	No token or API key provided	Add `Authorization: Bearer <token>` header
`INVALID_TOKEN`	JWT token is malformed or expired	Get a new token via `/auth/login`
`INVALID_API_KEY`	API key not found or revoked	Check your API key in the dashboard

Validation Errors (400)

Code	Description	Solution
`VALIDATION_ERROR`	Invalid request parameters	Check the `issues` array for details
`MARITIME_ROUTE_ERROR`	Cannot calculate sea route	Check if waypoints are over water or use `mode: "manual"`
`ROAD_ROUTE_ERROR`	Cannot calculate road route	Check if waypoints have road access

Permission Errors (403)

Code	Description	Solution
`EMAIL_NOT_VERIFIED`	Account email not verified	Check your email for verification link
`FEATURE_NOT_AVAILABLE`	Feature not in your tier	Upgrade your plan

Rate Limit Errors (429)

Code	Description	Solution
`RATE_LIMIT_EXCEEDED`	Too many API requests	Wait and retry with exponential backoff
`RENDER_LIMIT_EXCEEDED`	Monthly render quota exceeded	Wait for next billing period or upgrade
`CONCURRENT_JOB_LIMIT`	Too many jobs processing	Wait for a job to complete

Server Errors (500)

Code	Description	Solution
`RENDER_FAILED`	Render processing failed	Retry the request; contact support if persistent
`INTERNAL_ERROR`	Unexpected server error	Retry the request; contact support if persistent

Handling Errors in Code

Python

from georender.exceptions import (
    AuthenticationError,
    ValidationError,
    RateLimitError,
)

try:
    job = client.render(waypoints=[...])
except ValidationError as e:
    print(f"Validation failed: {e.message}")
    for issue in e.issues:
        print(f"  - {issue['field']}: {issue['message']}")
except RateLimitError as e:
    time.sleep(e.retry_after)
    # Retry the request

Node.js

import { ValidationError, RateLimitError } from '@georender/sdk';

try {
  const job = await client.render({ waypoints: [...] });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log(`Validation failed: ${error.message}`);
    error.issues.forEach(issue => {
      console.log(`  - ${issue.field}: ${issue.message}`);
    });
  } else if (error instanceof RateLimitError) {
    await sleep(error.retryAfter * 1000);
    // Retry the request
  }
}

LLM Context

The llm_context field provides structured information designed for AI assistants and automated systems to understand and resolve errors:

error_code - Machine-readable error identifier
summary - Human-readable summary
issues - Array of specific problems with suggestions
valid_options - Valid values for enum fields

Tip: When debugging, check the llm_context.issues array first - it contains specific suggestions for fixing each problem.