Error Codes

Every error uses the same envelope. Inspect error.code for programmatic handling and error.message for a human-readable explanation.

Error shape

All failures return:

{
  "success": false,
  "error": { "code": "INVALID_API_KEY", "message": "Invalid API key." }
}

Code	HTTP	When it occurs
MISSING_API_KEY	401	No Authorization header was provided.
INVALID_AUTH_HEADER	401	The header wasn't in the form 'Bearer <key>'.
INVALID_API_KEY	401	The key doesn't match any active key.
REVOKED_API_KEY	401	The key was permanently revoked.
INACTIVE_API_KEY	401	The key is currently disabled.
NO_ACCOUNT	403	The key has no associated owner account.

Code	HTTP	When it occurs
VALIDATION_ERROR	400	A required field is missing or invalid (mode, message, query, etc.).
UNSUPPORTED_FILE_TYPE	400	An uploaded file's type isn't supported.
FILE_TOO_LARGE	400	An uploaded file exceeds the size limit.
USAGE_LIMIT_REACHED	402	The account's usage/credit limit has been reached.
TOO_MANY_REQUESTS	429	The API key's daily rate limit was exceeded (see Rate Limits).

Code	HTTP	When it occurs
SESSION_NOT_FOUND	404	The session doesn't exist in this project (or belongs to another).
FILE_NOT_FOUND	404	The file doesn't exist for this account.
NOT_FOUND	404	No such /v1 endpoint at the requested path.

Code	HTTP	When it occurs
INTERNAL_ERROR	500	An unexpected error occurred. Safe to retry.

Cross-project access always surfaces as a 404 (not 403) so the existence of another project's resources is never revealed.