Error Codes

Complete catalog of error codes returned by the public API.

Error Codes

Every error response follows the same envelope:

{
  "success": false,
  "error": {
    "code":    "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked.",
    "status":  401
  }
}

The numeric status mirrors the HTTP status code; code is a machine-readable identifier you can branch on.

Catalog

Code	Status	Meaning
API_KEY_REQUIRED	401	The x-ansdev-key header was missing.
INVALID_API_KEY	401	Key not found or has been revoked.
API_KEY_EXPIRED	401	Key is past its expiresAt date.
INSUFFICIENT_SCOPE	403	Key lacks the scope required for this route (e.g. video:read).
RATE_LIMIT_EXCEEDED	429	Daily playback-token quota exceeded for this key.
VIDEO_NOT_FOUND	404	Video doesn’t exist, or the calling key doesn’t own it.
VIDEO_NOT_READY	400	Tried to mint a playback token for a job that isn’t COMPLETED.
PLAYBACK_TOKEN_EXPIRED	401	Playback JWT is past its 5-minute TTL.
PLAYBACK_TOKEN_INVALID	401	Playback JWT is malformed, tampered, or wrong scope.
PLAYBACK_TOKEN_MISMATCH	403	Token was issued for a different video than the one being requested.
NO_KEY	404	Asked for an AES key on a non-encrypted video.
KEY_DECRYPT_FAILED	500	Server-side encryption-key decryption failed (config drift — page us).

Handling errors

const res  = await fetch(url, { headers: { 'x-ansdev-key': key } });
const json = await res.json();

if (!json.success) {
  switch (json.error.code) {
    case 'API_KEY_EXPIRED':
    case 'INVALID_API_KEY':
      // → rotate key, prompt user
      break;
    case 'RATE_LIMIT_EXCEEDED':
      // → back off; X-RateLimit-Reset tells you when
      break;
    case 'VIDEO_NOT_FOUND':
      // → 404 in your UI
      break;
    default:
      // → show generic error, log code for support
  }
}

INVALID_API_KEY is also returned for revoked keys — there is no separate KEY_REVOKED code, by design. From a caller’s perspective the key just stopped working; rotate and move on.