Browse docs
Reference
Errors
Every error response follows RFC 7807 Problem Details.
4 min read
Shape
json
{
"type": "https://convoi.ai/errors/invalid-request",
"title": "Invalid request",
"status": 400,
"detail": "agent_id is required when type is \"web\".",
"code": "missing_field",
"request_id": "req_abc123"
}Show detail to your end users when surfacing errors. Always log request_id alongside; Convoi support can trace any request end-to-end from that ID alone.
Status codes
| Status | Meaning |
|---|---|
| 400 | Invalid request body or query parameters. |
| 401 | Missing, malformed, or revoked bearer token. |
| 403 | Token is valid but lacks scope for the requested resource. |
| 404 | Resource does not exist on this account. |
| 409 | Conflict: usually a duplicate idempotency key. |
| 422 | Validation failed (typed field error in detail). |
| 429 | Rate limit or monthly quota exceeded; honor Retry-After. |
| 5xx | Convoi-side issue; safe to retry with exponential backoff. |
Related in Reference