Skip to main content

​
Status code matrix

Status CodeDescriptionTypical Cause
200OKRequest succeeded
400Bad RequestInvalid params, missing fields, malformed input
401UnauthorizedMissing or invalid API key
403ForbiddenKey lacks required permission
404Not FoundResource does not exist or is not public
409ConflictDuplicate resource
422Unprocessable EntityMissing required properties or semantic validation failure
429Too Many RequestsRate limit exceeded
500Internal Server ErrorUnexpected server-side failure

​
Common error messages

ScenarioMessage
Missing API KeyNot authenticated.
Invalid API KeyNot authenticated.
Insufficient ScopeInsufficient API key scope.
Rate LimitedToo many requests. Please try again later.
Resource Not FoundResource not found.
Event Not PublicResource not found.

​
Recovery playbooks

Verify header format, key environment, and key lifecycle status. For Public API, prefer x-evento-api-key.
Ensure key has required permission(s), such as events:read for Public API.
Implement exponential backoff and queue requests when approaching daily quota.
Confirm IDs, usernames, and visibility constraints. Public endpoints only return published public resources.

​
Backoff example

async function fetchWithBackoff(url, options, maxRetries = 4) {
  for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
    const response = await fetch(url, options);

    if (response.status !== 429) return response;
    if (attempt === maxRetries) return response;

    const delayMs = 500 * Math.pow(2, attempt);
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }
}

​
Error payload example

{
  "success": false,
  "message": "Validation failed",
  "code": "validation_error"
}

​
Next steps

Authentication

Header requirements and auth behavior by surface.

Response format

Shared envelope and payload contracts.