Skip to main content

​
API Error Handling

When sending or retrieving events via the API, you may encounter the following response codes:
Status CodeDescription
202 AcceptedEvents are accepted and queued
400 Bad RequestInvalid request format or missing fields
401 UnauthorizedInvalid API key
422 Unprocessable EntityEvent validation failed
500 Internal Server ErrorError while processing the request
  • If events fail validation, the API returns 422 Unprocessable Entity with error details.
  • Users are notified asynchronously via webhooks, receiving an array of failed event_ids and the reason for failure.
Sample 422 Response
{
  "failed_events": [
    {
      "event_id": "fd6f47f4-83cf-42c7-ad70-63f0d7c86687",
      "reason": "Missing required field: event_type"
    }
  ]
}
If one or more events in a batch are missing an event_id, the entire batch will be rejected.

​
API Rate Limits

To ensure fair usage and platform stability, Quivly enforces rate limits on API requests.
  • Default Rate Limit: 100 requests per minute per API key (unless otherwise specified in your plan)
  • Response Code: If you exceed the rate limit, the API will return a 429 Too Many Requests status code.
Sample 429 Response
{
  "error": "Rate limit exceeded. Please wait before making more requests."
}
If you consistently exceed rate limits, your API access may be temporarily suspended. Consider implementing exponential backoff and monitoring your request volume.
To avoid hitting rate limits, batch your events and use efficient filtering when retrieving data.