Skip to main content

​
Response Codes

Comprehensive guide to Nimble Web API response codes, error handling, and troubleshooting.

​
HTTP Status Codes

​
Success Codes

​
200 OK

Request completed successfully. 
{
  "status": "success",
  "url": "https://example.com",
  "html": "<!DOCTYPE html>..."
}

​
202 Accepted

Request accepted for processing (async operations). 
{
  "job_id": "job_123456",
  "status": "queued",
  "estimated_completion": "2024-01-15T10:32:00Z"
}

​
Client Error Codes

​
400 Bad Request

Invalid request parameters. 
{
  "status": "error",
  "error": "BAD_REQUEST",
  "message": "Missing required parameter: url",
  "code": 400
}

​
401 Unauthorized

Invalid or missing API key. 
{
  "status": "error", 
  "error": "UNAUTHORIZED",
  "message": "Invalid API key provided",
  "code": 401
}

​
403 Forbidden

Access denied or insufficient permissions. 
{
  "status": "error",
  "error": "FORBIDDEN", 
  "message": "This feature requires a premium plan",
  "code": 403
}

​
404 Not Found

Endpoint or resource not found. 
{
  "status": "error",
  "error": "NOT_FOUND",
  "message": "Job ID job_123456 not found",
  "code": 404
}

​
422 Unprocessable Entity

Valid request but cannot be processed. 
{
  "status": "error",
  "error": "UNPROCESSABLE_ENTITY",
  "message": "URL format is invalid",
  "code": 422,
  "details": {
    "field": "url",
    "value": "not-a-valid-url"
  }
}

​
429 Too Many Requests

Rate limit exceeded. 
{
  "status": "error",
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Try again in 60 seconds",
  "code": 429,
  "retry_after": 60
}

​
Server Error Codes

​
500 Internal Server Error

Unexpected server error. 
{
  "status": "error",
  "error": "INTERNAL_SERVER_ERROR", 
  "message": "An unexpected error occurred",
  "code": 500,
  "request_id": "req_abc123"
}

​
502 Bad Gateway

Upstream service unavailable. 
{
  "status": "error",
  "error": "BAD_GATEWAY",
  "message": "Upstream service temporarily unavailable",
  "code": 502
}

​
503 Service Unavailable

Service temporarily unavailable. 
{
  "status": "error",
  "error": "SERVICE_UNAVAILABLE",
  "message": "Service under maintenance", 
  "code": 503,
  "retry_after": 300
}

​
Scraping-Specific Codes

​
Target Website Errors

​
URL_NOT_ACCESSIBLE

Target URL returned an error or is inaccessible. 
{
  "status": "error",
  "error": "URL_NOT_ACCESSIBLE",
  "message": "Target URL returned 404 Not Found",
  "target_status_code": 404,
  "url": "https://example.com/missing-page"
}

​
TIMEOUT_EXCEEDED

Request timed out before completion. 
{
  "status": "error", 
  "error": "TIMEOUT_EXCEEDED",
  "message": "Request timed out after 30 seconds",
  "timeout": 30000,
  "url": "https://slow-loading-site.com"
}

​
BLOCKED_REQUEST

Request was blocked by the target website. 
{
  "status": "error",
  "error": "BLOCKED_REQUEST", 
  "message": "Request blocked by target website",
  "block_reason": "rate_limited",
  "url": "https://protected-site.com"
}

​
Content Processing Errors

​
RENDER_ERROR

JavaScript rendering failed. 
{
  "status": "error", 
  "error": "RENDER_ERROR",
  "message": "JavaScript rendering failed",
  "render_details": {
    "error": "Page crashed during rendering",
    "console_errors": ["TypeError: Cannot read property 'x' of null"]
  }
}

​
PARSING_ERROR

Failed to parse response content. 
{
  "status": "error",
  "error": "PARSING_ERROR",
  "message": "Failed to parse JSON response",
  "parsing_details": {
    "expected_format": "json",
    "actual_content_type": "text/html"
  }
}

​
Action-Specific Errors

​
ELEMENT_NOT_FOUND

Required element not found on page. 
{
  "status": "error",
  "error": "ELEMENT_NOT_FOUND",
  "message": "Element with selector '.target-button' not found",
  "selector": ".target-button",
  "action": "wait_and_click"
}

​
ACTION_FAILED

Page interaction action failed. 
{
  "status": "error",
  "error": "ACTION_FAILED",
  "message": "Click action failed - element not clickable",
  "action": "wait_and_click",
  "selector": ".disabled-button",
  "reason": "element_disabled"
}

​
Warning Codes

​
Partial Success

{
  "status": "partial_success",
  "url": "https://example.com",
  "html": "<!DOCTYPE html>...",
  "warnings": [
    {
      "code": "SLOW_RESPONSE",
      "message": "Target site responded slowly (15.2s)",
      "severity": "medium"
    }
  ]
}

​
Content Warnings

{
  "status": "success",
  "url": "https://example.com", 
  "html": "<!DOCTYPE html>...",
  "warnings": [
    {
      "code": "CAPTCHA_DETECTED",
      "message": "CAPTCHA detected but bypassed",
      "severity": "low"
    },
    {
      "code": "ANTI_BOT_DETECTED", 
      "message": "Stealth measures detected and handled",
      "severity": "medium"
    }
  ]
}

​
Error Handling Best Practices

​
Retry Logic

async function scrapeWithRetry(url, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const result = await client.scrape({ url });
      return result;
    } catch (error) {
      if (error.code === 429) {
        // Rate limited - wait before retry
        await delay(error.retry_after * 1000);
      } else if (error.code >= 500) {
        // Server error - exponential backoff
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        // Client error - don't retry 
        throw error;
      }
      
      if (attempt === maxRetries) {
        throw error;
      }
    }
  }
}

​
Status Code Handling

function handleResponse(response) {
  switch (response.status) {
    case 'success':
      return response.html;
      
    case 'partial_success':
      console.warn('Warnings:', response.warnings);
      return response.html;
      
    case 'error':
      switch (response.error) {
        case 'RATE_LIMIT_EXCEEDED':
          throw new RateLimitError(response.message, response.retry_after);
          
        case 'URL_NOT_ACCESSIBLE':
          throw new TargetError(response.message, response.target_status_code);
          
        case 'TIMEOUT_EXCEEDED':
          throw new TimeoutError(response.message, response.timeout);
          
        default:
          throw new ScrapingError(response.message, response.error);
      }
  }
}

​
Monitoring Response Codes

​
Dashboard Metrics

Monitor common response codes in your dashboard:
  • Success rate: Percentage of successful requests
  • Error breakdown: Distribution of error types
  • Response times: Average and 95th percentile times
  • Rate limit hits: Frequency of 429 responses

​
Alerting

Set up alerts for:
  • High error rates (>5% failures)
  • Frequent timeouts (>10% timeout errors)
  • Rate limit violations (repeated 429s)
  • Service availability (502/503 errors)

​
SDK Error Handling

​
Node.js

try {
  const result = await client.scrape({ url: 'https://example.com' });
  console.log(result.html);
} catch (error) {
  if (error.code === 429) {
    console.log(`Rate limited. Retry after ${error.retry_after} seconds`);
  } else if (error.code >= 500) {
    console.log('Server error. Retrying...');
  } else {
    console.error('Client error:', error.message);
  }
}

​
Python

from nimble_sdk import NimbleClient, RateLimitError, ServerError

try:
    result = client.scrape({'url': 'https://example.com'})
    print(result['html'])
except RateLimitError as e:
    print(f'Rate limited. Retry after {e.retry_after} seconds')
except ServerError as e:
    print(f'Server error: {e.message}')
except Exception as e:
    print(f'Client error: {e.message}')

​
Troubleshooting Guide

​
Common Issues

​
401 Unauthorized

  • Check API key is correct and active
  • Verify headers include proper Authorization
  • Check account status for suspensions

​
429 Rate Limit

  • Implement exponential backoff with retry logic
  • Reduce request frequency or upgrade plan
  • Use batch processing for multiple URLs

​
URL_NOT_ACCESSIBLE

  • Verify target URL is accessible in browser
  • Check for redirects or changed URLs
  • Try different proxy locations if geo-blocked

​
TIMEOUT_EXCEEDED

  • Increase timeout for slow-loading sites
  • Disable JavaScript rendering if not needed
  • Use simpler selectors for page interactions

​
Support Contact

For persistent issues:
  • Include request_id from error responses
  • Provide example URLs that are failing
  • Share relevant error messages and codes
  • Mention your plan type and usage patterns