Nodium Screenshot API -- Error Reference

{
  "error": {
    "code": "error_code_here",
    "message": "Human-readable description of the error."
  }
}

{
  "error": {
    "code": "access_key_required",
    "message": "An access key is required. Provide it via the access_key parameter, X-Access-Key header, or JSON body."
  }
}

{
  "error": {
    "code": "access_key_invalid",
    "message": "The provided access key is invalid or has been revoked."
  }
}

{
  "error": {
    "code": "access_key_suspended",
    "message": "Your account has been suspended. Please contact support."
  }
}

{
  "error": {
    "code": "request_not_valid",
    "message": "Exactly one source parameter (url, html, or markdown) is required."
  }
}

{
  "error": {
    "code": "url_not_valid",
    "message": "The URL 'example.com' is not valid. URLs must start with http:// or https://."
  }
}

{
  "error": {
    "code": "url_not_reachable",
    "message": "The URL 'https://down.example.com' could not be reached. Connection refused."
  }
}

{
  "error": {
    "code": "html_too_large",
    "message": "The HTML content exceeds the maximum allowed size of 2MB."
  }
}

{
  "error": {
    "code": "format_not_supported",
    "message": "The format 'bmp' is not supported. Supported formats: png, jpeg, webp, avif, heif, tiff, jp2, gif, pdf, html, markdown."
  }
}

{
  "error": {
    "code": "screenshots_limit_reached",
    "message": "Monthly screenshot limit reached (10000/10000). Upgrade your plan or wait for the next billing period."
  }
}

{
  "error": {
    "code": "credits_exhausted",
    "message": "Your credit balance is exhausted. Purchase additional credits to continue."
  }
}

{
  "error": {
    "code": "concurrency_limit_reached",
    "message": "Concurrency limit reached (10/10). Wait for ongoing requests to complete."
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 5 seconds."
  }
}

{
  "error": {
    "code": "timeout_error",
    "message": "The operation timed out after 60 seconds."
  }
}

{
  "error": {
    "code": "network_error",
    "message": "Failed to connect to 'https://example.com'. Connection timed out."
  }
}

{
  "error": {
    "code": "rendering_error",
    "message": "An error occurred while rendering the page."
  }
}

{
  "error": {
    "code": "storage_error",
    "message": "Failed to upload screenshot to S3 bucket 'my-bucket'. Access denied."
  }
}

{
  "error": {
    "code": "internal_application_error",
    "message": "An internal error occurred. Please retry your request."
  }
}

{
  "error": {
    "code": "temporary_unavailable",
    "message": "The service is temporarily unavailable. Please retry shortly."
  }
}

import time
import random
import requests

def take_screenshot(params, max_retries=5):
    base_delay = 1  # seconds

    for attempt in range(max_retries):
        response = requests.get(
            "https://api.nodium.io/api/v1/screenshot/take",
            params=params,
            headers={"X-Access-Key": "YOUR_KEY"}
        )

        if response.status_code == 200:
            return response.content

        error = response.json().get("error", {})
        error_code = error.get("code", "")

        # Do not retry non-retryable errors
        non_retryable = [
            "access_key_required", "access_key_invalid", "access_key_suspended",
            "request_not_valid", "url_not_valid", "html_too_large",
            "format_not_supported", "screenshots_limit_reached", "credits_exhausted"
        ]
        if error_code in non_retryable:
            raise Exception(f"Non-retryable error: {error_code} - {error.get('message')}")

        # Respect Retry-After header if present
        retry_after = response.headers.get("Retry-After")
        if retry_after:
            delay = int(retry_after)
        else:
            # Exponential backoff with jitter
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)

        print(f"Attempt {attempt + 1} failed ({error_code}). Retrying in {delay:.1f}s...")
        time.sleep(delay)

    raise Exception(f"Max retries ({max_retries}) exceeded")

async function takeScreenshot(params, maxRetries = 5) {
  const nonRetryable = [
    "access_key_required", "access_key_invalid", "access_key_suspended",
    "request_not_valid", "url_not_valid", "html_too_large",
    "format_not_supported", "screenshots_limit_reached", "credits_exhausted"
  ];

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const url = new URL("https://api.nodium.io/api/v1/screenshot/take");
    Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));

    const response = await fetch(url, {
      headers: { "X-Access-Key": "YOUR_KEY" }
    });

    if (response.ok) {
      return await response.arrayBuffer();
    }

    const { error } = await response.json();

    if (nonRetryable.includes(error.code)) {
      throw new Error(`Non-retryable: ${error.code} - ${error.message}`);
    }

    const retryAfter = response.headers.get("Retry-After");
    const delay = retryAfter
      ? parseInt(retryAfter) * 1000
      : Math.min(1000 * Math.pow(2, attempt) + Math.random() * 1000, 30000);

    console.log(`Attempt ${attempt + 1} failed (${error.code}). Retrying in ${delay}ms...`);
    await new Promise(resolve => setTimeout(resolve, delay));
  }

  throw new Error(`Max retries (${maxRetries}) exceeded`);
}

response=$(curl -s -w "\n%{http_code}" \
  "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png")

http_code=$(echo "$response" | tail -1)

if [ "$http_code" -ne 200 ]; then
  echo "Error: HTTP $http_code"
  echo "$response" | head -n -1
  exit 1
fi

curl -s "https://api.nodium.io/api/v1/screenshot/usage?access_key=KEY" | jq .