Errors
Error response format and status codes.
All API errors return a JSON object with an error field and an appropriate HTTP status code.
Error Format
{
"error": "Human-readable error message"
}For validation errors (422), the error field contains a JSON-stringified array of Zod validation issues:
{
"error": "[{\"code\":\"too_small\",\"minimum\":1,\"type\":\"string\",\"inclusive\":true,\"exact\":false,\"message\":\"String must contain at least 1 character(s)\",\"path\":[\"name\"]}]"
}Status Codes
| Code | Meaning | When |
|---|---|---|
200 | OK | Successful read or update |
201 | Created | Record successfully created |
307 | Redirect | File download (redirects to signed URL) |
400 | Bad Request | Malformed request or missing required fields |
401 | Unauthorized | Missing or invalid authentication |
403 | Forbidden | Authenticated but insufficient permissions |
404 | Not Found | Record does not exist |
409 | Conflict | Duplicate or state conflict (e.g., lead already converted) |
422 | Unprocessable Entity | Request body fails Zod validation |
500 | Internal Server Error | Unexpected server error |
OAuth Error Format
The /api/oauth/token endpoint uses the standard OAuth 2.0 error format:
{
"error": "invalid_grant",
"error_description": "Authorization code is invalid or expired"
}| Error Code | Description |
|---|---|
unsupported_grant_type | Only authorization_code is supported |
invalid_request | Missing required OAuth parameters |
invalid_client | Unknown client or client authentication failed |
invalid_grant | Code expired, already used, PKCE mismatch, or redirect URI mismatch |