Skip to main content

​
Rate limits and constraints

LimitValue
Users per request1,000
Maximum payload size10 MB
Request timeout10 seconds
If you need higher limits for bulk imports or high-throughput pipelines, contact us at support@revbridge.ai.

​
HTTP status codes

StatusMeaningAction
202Accepted — at least one user was processed successfullyCheck users_rejected for partial failures
400Bad Request — invalid payload or all users failed validationFix the errors listed in the response and retry
401Unauthorized — missing or invalid API key / customer IDVerify your Authorization and x-customer-id headers
405Method Not Allowed — wrong HTTP methodUse POST for the ingest endpoint
413Payload Too Large — body exceeds 10 MBSplit your data into smaller batches
503Service Unavailable — temporary processing issueRetry 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

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
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
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.
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.
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.
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.
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".
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.
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.
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.