Limits & Error Handling

API limits, error codes, and troubleshooting guide for the Events API.

Rate limits and constraints

Limit	Value
Users per request	1,000
Maximum payload size	10 MB
Request timeout	10 seconds

If you need higher limits for bulk imports or high-throughput pipelines, contact us at [e-mail].

HTTP status codes

Status	Meaning	Action
202	Accepted — at least one user was processed successfully	Check users_rejected for partial failures
400	Bad Request — invalid payload or all users failed validation	Fix the errors listed in the response and retry
401	Unauthorized — missing or invalid API key / customer ID	Verify your Authorization and x-customer-id headers
405	Method Not Allowed — wrong HTTP method	Use POST for the ingest endpoint
413	Payload Too Large — body exceeds 10 MB	Split your data into smaller batches
503	Service Unavailable — temporary processing issue	Retry with exponential backoff

Error response formats

Validation errors (400 / 202 with rejected users)

When users fail validation, the response includes an errors array with the index of the failed user and a message describing the issue.

{
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "users_accepted": 1,
  "users_rejected": 2,
  "errors": [
    {
      "userIndex": 1,
      "message": "identifiers is required"
    },
    {
      "userIndex": 2,
      "message": "events[0]: event_name is required"
    }
  ]
}

The userIndex corresponds to the zero-based position in the users array of your request.

Full-rejection errors (400)

When all users in the request fail validation, the response uses the error format:

{
  "error": "validation failed",
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "errors": [
    {
      "userIndex": 0,
      "message": "at least one identifier is required (user_id, email, phone_number, or anon_id)"
    }
  ]
}

Authentication errors (401)

{
  "error": "unauthorized"
}

Service errors (503)

{
  "error": "service temporarily unavailable",
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Troubleshooting

401 — 'unauthorized'

Possible causes:

• Missing Authorization header
• API key does not start with Bearer prefix
• Invalid or revoked API key
• Missing x-customer-id header
• The API key does not belong to the specified customer ID

Resolution:

1. Verify you are sending both headers: Authorization: Bearer <KEY> and x-customer-id: <ID>
2. Check that your API key is active in Settings → API Keys
3. Ensure the customer ID matches the account that owns the API key

400 — 'invalid JSON body'

Possible causes:

• Malformed JSON (missing commas, unclosed brackets, etc.)
• Body is empty or not valid JSON
• Content-Type header is not application/json

Resolution:

1. Validate your JSON with a linter before sending
2. Ensure the Content-Type: application/json header is set
3. Check that the request body is not empty

400 — 'users array is required and must not be empty'

Possible causes:

• The users field is missing from the JSON body
• The users array is empty ([])

Resolution: Include at least one user object in the users array.

400 — 'at least one identifier is required'

Possible causes:

• The identifiers object is missing or empty
• None of the four primary identifiers (user_id, email, phone_number, anon_id) are present

Resolution: Add at least one primary identifier to the user’s identifiers object.

400 — 'events array is required and must not be empty'

Possible causes:

• The events field is missing from a user object
• The events array is empty

Resolution: Include at least one event for each user.

400 — 'event_name is required'

Possible causes:

• An event object is missing the event_name field
• The event_name value is an empty string

Resolution: Every event must have a non-empty event_name string.

400 — 'revenue must be a number'

Possible causes:

• The revenue field is a string instead of a number
• The value is not a valid number

Resolution: Send revenue as a numeric value: "revenue": 49.99, not "revenue": "49.99".

400 — 'timestamp must be valid ISO 8601'

Possible causes:

• The timestamp is in a non-standard format
• Invalid date values

Resolution: Use ISO 8601 format: 2026-01-15T14:30:00Z or 2026-01-15T14:30:00.

413 — Payload Too Large

Possible causes:

• The request body exceeds 10 MB

Resolution: Split your data into smaller batches. Reduce the number of users per request or remove unnecessary properties.

503 — Service Unavailable

Possible causes:

• Temporary service disruption

Resolution: Retry the request with exponential backoff. Start with a 1-second delay and double it on each retry, up to a maximum of 60 seconds. Check status.revbridge.ai for any ongoing incidents.

Retry strategy

For 503 responses and network errors, implement exponential backoff:

async function sendWithRetry(payload, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch("https://api.revbridge.ai/ingest/events", {
        method: "POST",
        headers: {
          "Authorization": "Bearer rbk_a1b2c3d4e5f6g7h8",
          "x-customer-id": "cust_abc123",
          "Content-Type": "application/json",
        },
        body: JSON.stringify(payload),
      });

      if (response.status === 503) {
        const delay = Math.min(1000 * Math.pow(2, attempt), 60000);
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }

      return await response.json();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      const delay = Math.min(1000 * Math.pow(2, attempt), 60000);
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

Only retry on 503 and network errors. Do not retry 202 responses — even if some users were rejected, the accepted users were already processed. Fix the rejected users and send them in a new request.