Error Codes

When an error occurs, the API returns a JSON response with an error code and message.

Error Response Format

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

Authentication Errors

Error Code	HTTP Status	Description
access_key_required	400	No access key was provided in the request.
access_key_invalid	400	The provided access key is incorrect or inactive.
signature_is_required	400	Request signing is enabled but no signature was provided.
signature_is_not_valid	400	The signature doesn't match the expected value.

Rate Limiting Errors

Error Code	HTTP Status	Description
concurrency_limit_reached	429	Too many simultaneous requests. Wait and retry.
temporary_unavailable	503	API is temporarily overloaded. Retry with exponential backoff.

Request Validation Errors

Error Code	HTTP Status	Description
request_not_valid	400	Invalid request parameters. Check the error details.
invalid_cookie_parameter	400	The cookie parameter is malformed.
invalid_header_parameter	400	A custom header parameter is malformed.
request_body_too_large	413	Request body exceeds the size limit.

Rendering Errors

Error Code	HTTP Status	Description
name_not_resolved	400	The domain name could not be resolved (DNS error).
network_error	500	Could not connect to the target URL.
host_returned_error	500	The target site returned a non-2xx HTTP status.
timeout_error	500	The screenshot timed out before completing.
selector_not_found	400	The specified CSS selector was not found on the page.
resulting_image_too_large	400	The output image exceeds the maximum size limit.
script_triggers_redirect	400	Injected scripts caused an unexpected redirect.

Content Validation Errors

Error Code	HTTP Status	Description
content_contains_specified_string	500	Page contains a string specified in fail_if_content_contains.
matched_failed_request	500	A request matched the fail_if_request_failed pattern.

Storage Errors

Error Code	HTTP Status	Description
invalid_storage_configuration	400	S3 bucket configuration is incorrect.
storage_access_denied	400	Cannot access the storage bucket. Check credentials.
storage_returned_transient_error	500	Storage service returned a temporary error. Safe to retry.

Internal Errors

Error Code	HTTP Status	Description
internal_application_error	500	An internal error occurred. Safe to retry.
request_aborted	500	The request was cancelled during execution.

Handling Errors

Best practices for error handling:

• Retry on 5xx errors — These are typically transient and safe to retry with exponential backoff.
• Don't retry on 4xx errors — These indicate a problem with your request that won't be resolved by retrying.
• Check error details — The message field provides human-readable context.
• Log the error code — Use the code field for programmatic error handling.

Example: Retry Logic

async function takeScreenshot(url, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(`https://api.lambdashot.com/take?url=${url}&access_key=YOUR_KEY`);

    if (response.ok) {
      return response.blob();
    }

    const error = await response.json();

    // Don't retry client errors
    if (response.status < 500) {
      throw new Error(error.error.message);
    }

    // Exponential backoff for server errors
    await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
  }

  throw new Error('Max retries exceeded');
}