Errors
Collect uses conventional HTTP status codes and returns a consistent JSON error envelope so you can branch on a stable code rather than parsing messages.
Error shape#
Every error carries a stable code, a human-readable message, and an optional details object:
{
"code": "validation_failed",
"message": "Validation failed",
"details": {
"fieldErrors": { "email": "Invalid email" }
}
}Status codes#
| Code | HTTP | When |
|---|---|---|
| bad_request | 400 | Malformed request — e.g. invalid JSON or a bad query parameter. |
| unauthorized | 401 | Missing, invalid, or revoked API key. |
| forbidden | 403 | API not enabled for the workspace, or the key lacks a scope. |
| not_found | 404 | The resource doesn't exist in your workspace. |
| conflict | 409 | The request conflicts with existing state (e.g. a duplicate email). |
| validation_failed | 422 | The body failed validation. See details.fieldErrors. |
| idempotency_in_flight | 425 | An earlier request with the same Idempotency-Key is still running. |
| rate_limited | 429 | Too many requests. See details.retryAfterMs. |
| internal_error | 500 | Something went wrong on our side. Safe to retry. |
A reused Idempotency-Key with a different body returns 409 idempotency_conflict — see the idempotency guide.