External API
Errors
Error status and response guidance for API clients.
API errors currently return JSON with an error field.
{
"error": "Unauthorized"
}Status Codes
| Status | Meaning | Common causes |
|---|---|---|
400 | Bad request | Missing tenantId, missing task fields, or invalid JSON body. |
401 | Unauthorized | Missing key, invalid key, expired key, inactive key, revoked key, wrong tenant, missing scope, or missing user session. |
405 | Method not allowed | Calling an endpoint with an unsupported HTTP method. |
Convex or platform errors may return other status codes if the request fails before the handler completes.
Client Behavior
- Treat
401as non-retryable until credentials or scopes change. - Treat missing IDs as a signal to refresh reference data.
- Do not log raw API keys in error messages.
- Include request IDs or external correlation IDs in your own logs when possible.
CORS
The current external API sends CORS headers for:
AuthorizationContent-TypeX-API-Key
Browser-based integrations should preflight before relying on a new method or header.