Skip to main content

​
Overview

The Error Ingestion API receives error events from your application via the SDK. It supports both single error ingestion and batch uploads for efficient data transmission.

​
Authentication

Error ingestion uses API key in payload authentication. Include your project API key in the request body. See Authentication for details.

​
Single Error Ingestion

Send a single error event to Proliferate. 
curl -X POST https://api.proliferate.com/api/v1/errors \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "pk_abc123def456ghi789",
    "event_id": "evt_1234567890abcdef",
    "timestamp": "2025-01-15T10:30:00.123Z",
    "type": "exception",
    "level": "error",
    "environment": "production",
    "release": "v1.2.3",
    "url": "https://example.com/dashboard",
    "user_agent": "Mozilla/5.0...",
    "exception": {
      "type": "TypeError",
      "message": "Cannot read property '\''foo'\'' of undefined",
      "stack": "TypeError: Cannot read property '\''foo'\'' of undefined\n    at processData (app.js:42:15)\n    at handleClick (app.js:120:5)"
    },
    "user": {
      "id": "user_abc123",
      "email": "[email protected]"
    },
    "account": {
      "id": "acct_xyz789",
      "name": "Acme Corp"
    },
    "session_id": "sess_abcdef123456",
    "window_id": "win_ghijkl789012",
    "breadcrumbs": [
      {
        "timestamp": 1736938195000,
        "category": "navigation",
        "message": "Navigated to /dashboard",
        "level": "info"
      },
      {
        "timestamp": 1736938198000,
        "category": "click",
        "message": "Clicked button#submit",
        "level": "info",
        "data": {
          "element": "button#submit"
        }
      }
    ],
    "extra": {
      "component": "Dashboard",
      "props": {
        "view": "overview"
      }
    }
  }'

​
Endpoint

POST /api/v1/errors

​
Request Schema

​
api_key
string
required
Your project API key (format: pk_...)
​
event_id
string
required
Unique identifier for this event (generated by SDK)
​
timestamp
string (ISO 8601)
required
When the error occurred
​
type
string
required
Event type: exception or message
​
level
string
default:"error"
Severity level: error, warning, or info
​
environment
string
Environment where error occurred (e.g., production, staging)
​
release
string
Release version or git commit SHA
​
url
string
URL where the error occurred
​
user_agent
string
Browser or client user agent string
​
exception
object
Exception details (required if type is exception)
​
message
string
Custom message (required if type is message)
​
user
object
User context
​
account
object
Account/organization context (B2B apps)
​
session_id
string
Session identifier for replay correlation
​
window_id
string
Window identifier (for multi-tab tracking)
​
breadcrumbs
array
List of events leading up to the error
​
extra
object
Additional custom context data

​
Response

Success (202 Accepted): 
{
  "event_id": "evt_1234567890abcdef"
}
Error (401 Unauthorized): 
{
  "detail": "Invalid API key"
}

​
Batch Error Ingestion

Send multiple error events in a single request for efficiency. The SDK uses this endpoint to batch errors collected over a time window. 
curl -X POST https://api.proliferate.com/api/v1/errors/batch \
  -H "Content-Type: application/json" \
  -d '[
    {
      "api_key": "pk_abc123def456ghi789",
      "event_id": "evt_001",
      "timestamp": "2025-01-15T10:30:00Z",
      "type": "exception",
      "exception": {
        "type": "TypeError",
        "message": "Cannot read property '\''x'\'' of undefined",
        "stack": "..."
      }
    },
    {
      "api_key": "pk_abc123def456ghi789",
      "event_id": "evt_002",
      "timestamp": "2025-01-15T10:30:05Z",
      "type": "exception",
      "exception": {
        "type": "ReferenceError",
        "message": "foo is not defined",
        "stack": "..."
      }
    }
  ]'

​
Endpoint

POST /api/v1/errors/batch

​
Request Schema

Body: Array of error events (max 100 events per batch) Each event follows the same schema as single error ingestion.

​
Response

Success (202 Accepted): 
{
  "processed": 2,
  "results": [
    {
      "event_id": "evt_001",
      "status": "ok"
    },
    {
      "event_id": "evt_002",
      "status": "ok"
    }
  ]
}
Partial Success: 
{
  "processed": 2,
  "results": [
    {
      "event_id": "evt_001",
      "status": "ok"
    },
    {
      "event_id": "evt_002",
      "status": "rejected",
      "reason": "Invalid API key"
    }
  ]
}

​
Error Grouping

Errors are automatically grouped into issues based on a fingerprint derived from:
  • Exception type
  • Top 3 stack frames (function name + file name)
Line numbers are intentionally excluded so code changes don’t split existing issues. Example: 
TypeError at processData (utils.js) -> handleClick (app.js) -> onClick (index.js)
All errors with this signature are grouped together, regardless of which line they occurred on.

​
What Happens After Ingestion?

1

Fingerprinting

Error is fingerprinted based on exception type and stack trace
2

Issue Creation or Update

If an issue with this fingerprint exists, increment its count. Otherwise, create a new issue.
3

User & Account Tracking

If user/account context is provided, track affected users and accounts
4

Stack Trace Resolution

If release is provided and source maps exist, resolve minified stack traces to original source
5

Notifications

Trigger notifications based on organization preferences

​
Best Practices

​
Always Include Context

The more context you provide, the easier it is to debug:
  • User context: Identify which users are affected
  • Account context: See which customers are impacted (B2B apps)
  • Release: Enable source map resolution
  • Breadcrumbs: Understand the sequence of events
  • Extra data: Add custom context relevant to your app

​
Use Consistent IDs

  • User IDs: Use the same ID format across your app
  • Account IDs: Use your internal account/organization ID
  • Event IDs: Let the SDK generate these (UUIDs)

​
Set Appropriate Levels

  • error: Unhandled exceptions, critical failures
  • warning: Handled errors, recoverable issues
  • info: Informational messages (use sparingly)

​
Batch When Possible

The SDK automatically batches errors to reduce network overhead. If implementing custom ingestion, batch errors collected within a few seconds.

​
Handle Rate Limits

If you hit rate limits (unlikely with normal usage):
  • Implement exponential backoff
  • Queue events locally and retry
  • Alert your team to investigate the error spike

​
Testing

Test error ingestion with a simple cURL command: 
curl -X POST https://api.proliferate.com/api/v1/errors \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "event_id": "test_'$(date +%s)'",
    "timestamp": "'$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")'",
    "type": "exception",
    "exception": {
      "type": "TestError",
      "message": "This is a test error from cURL",
      "stack": "TestError: This is a test\n    at test.js:1:1"
    }
  }'
Check the dashboard to verify the error appears.