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

500

Internal Server Error

Server error occurred

502

Bad Gateway

Invalid response from external service

503

Service Unavailable

Service temporarily unavailable

Common Error Examples

401

Unauthenticated

Missing or invalid API key

{
  "message": "Unauthenticated"
}
403

Forbidden

No active subscription or out of 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."]
  }
}

Error Handling Best Practices

Always check the HTTP status code before processing the response
Implement retry logic for transient errors (500, 502, 503)
Use exponential backoff when retrying requests
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

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)}`);
        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