Errors and limits
Failures return a JSON error with an HTTP status, and usually a stable code.
Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The token request body is malformed or grant_type is missing. |
| 400 | unsupported_grant_type | Only client_credentials is supported. |
| 400 | invalid_scope | A requested scope is not granted to this app. |
| 401 | invalid_client | The client id or secret is wrong. |
| 401 | message | The API key or access token is missing, invalid, expired or revoked. |
| 403 | scope_required | The key or token lacks the scope this call needs. |
| 403 | capability_required | The organization does not have the platform capability. |
| 413 | payload_too_large | The request body is over the size limit. |
| 422 | invalid_json | The body is not valid JSON. |
| 422 | too_many_events | The batch holds more events than the limit. |
| 422 | idempotency_key_too_long | The Idempotency-Key header is over 128 characters. |
| 429 | rate_limited | Too many requests; wait for the Retry-After seconds. |
Error shapes
Errors from the token endpoint and from every other endpoint have different JSON shapes. When code is a dash above, read the detail message instead.
Token endpoint
{
"error": "<code>",
"error_description": "<message>"
}All other endpoints
{
"detail": "<code or message>"
}Limits
| Limit | Value |
|---|---|
| Requests per minute | 60 |
| Burst | 120 |
| Events per batch | 100 |
| Maximum body size | 262144 bytes |
| Idempotency window | 7 days |
Idempotency
Send a stable id per event so a retried request is not processed twice; duplicates are recognised for 7 days. On rate-limit errors, wait and retry with backoff.