Errors

Learn how to handle API errors in your application.

Error Response Format

All errors return a JSON object with an error field:

{
  "error": "Error message describing what went wrong"
}

HTTP Status Codes

400Bad Request

The request was invalid. Check your parameters or request body.

Common causes:

Missing required parameter (e.g., email)
Invalid JSON body
Email array exceeds 100 items (batch check)
Invalid cursor format

401Unauthorized

Invalid or missing API key.

Common causes:

Missing X-API-Key header
Invalid API key format
Revoked API key

403Forbidden

You don't have permission to access this resource.

Common causes:

API key doesn't have access to this project
Project belongs to a different user

404Not Found

The requested resource doesn't exist.

Common causes:

Invalid project ID
Suppression hash doesn't exist (when deleting)
Invalid endpoint URL

429Too Many Requests

Rate limit exceeded. Slow down your requests.

See rate limits for your plan.

500Internal Server Error

Something went wrong on our end. Try again later.

If the issue persists, contact support@parsebounce.com

Handling Errors

Always check the HTTP status code and handle errors gracefully:

const response = await fetch(url, {
  headers: { 'X-API-Key': apiKey }
});

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

  switch (response.status) {
    case 401:
      // Invalid API key - check your credentials
      break;
    case 403:
      // No access to this project
      break;
    case 404:
      // Resource not found
      break;
    case 429:
      // Rate limited - wait and retry
      break;
    default:
      // Other error
      console.error(error.error);
  }
  return;
}

const data = await response.json();

← Suppressions Examples →