Skip to content
Scrappa Get API key
Consistent JSON Errors

Error Handling

The Scrappa API uses standard HTTP status codes and returns errors in a consistent JSON format for easy handling.

Error Response Format

All errors follow a consistent JSON structure: 

{
  "message": "Error description",
  "error": "Optional error type"
}

HTTP Status Codes

200

Success

Request completed successfully

400

Bad Request

Invalid parameters or malformed request

401

Unauthenticated

Missing or invalid API key

403

Forbidden

No active subscription or out of credits

404

Not Found

Endpoint or resource not found

422

Validation Error

Request validation failed

429

Rate Limited

Too many requests in a short time window

500

Internal Server Error

Server error occurred

502

Bad Gateway

Invalid response from external service

503

Service Unavailable

Service temporarily unavailable

Recovery Actions

Use these links when a Playground or API response needs an immediate next step:

401 Fix authentication Create, copy, or rotate the API key used in your X-API-KEY header. Manage API keys
403 Restore credits Buy credits or choose an active credit package before retrying the request. Open Credits
422 Match endpoint parameters Compare your payload with the OpenAPI reference, required fields, and examples. View OpenAPI docs
429 Slow retries down Add exponential backoff and avoid retrying all failed requests at once. Read retry guidance

Common Error Examples

401

Unauthenticated

Missing or invalid API key

{
  "message": "Unauthenticated"
}

Next action: open API keys and confirm your request uses the current token in the X-API-KEY header.

403

Forbidden

No active subscription or out of credits

Next action: open Credits and purchase or activate a package with available credits.

422

Validation Error

Invalid request parameters

{
  "message": "Validation failed",
  "errors": {
    "q": ["The q field is required."],
    "location": ["The location must be a valid location."]
  }
}

Next action: open the OpenAPI docs for required parameters, accepted values, and working examples.

429

Rate Limited

Too many requests in a short time window

{
  "message": "Too many requests. Please retry after a short delay."
}

Next action: follow the retry guidance below and increase delay before resending requests.

Error Handling Best Practices

Always check the HTTP status code before processing the response
Implement retry logic for transient errors (429, 500, 502, 503)
Use exponential backoff when retrying requests and add jitter before high-volume retries
Log error responses for debugging and monitoring
Display user-friendly error messages based on the error type
Handle validation errors (422) by showing specific field errors
For 401/403 errors, prompt users to check their API key or subscription

Retry guidance for 429 and transient errors

Retry 429, 500, 502, and 503 responses with exponential backoff, such as 1s, 2s, 4s, and 8s. Stop after a small retry budget, add jitter so parallel workers do not retry together, and do not retry 401, 403, or 422 until the API key, credits, or request parameters are fixed.

Example Error Handling

Here's how to properly handle errors in your application: 

async function handleApiRequest(url, apiKey) {
  try {
    const response = await fetch(url, {
      headers: {
        'X-API-KEY': apiKey
      }
    });

    if (!response.ok) {
      const error = await response.json();

      switch (response.status) {
        case 401:
          throw new Error('Invalid API key. Please check your credentials.');
        case 403:
          throw new Error('Access denied. Please check your subscription.');
        case 422:
          const validationErrors = error.errors || {};
          throw new Error(`Validation failed: \${JSON.stringify(validationErrors)}`);
        case 429:
          throw new Error('Rate limited. Retry with exponential backoff before sending more requests.');
        default:
          throw new Error(error.message || 'An error occurred');
      }
    }

    return await response.json();
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

Pro Tip

Use the interactive Playground to test API calls and see error responses in real-time before implementing in your code.

← Back to Home