Error codes

Errors use a consistent envelope with a stable machine-readable code:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This request requires the 'clips:read' scope.",
    "details": { "required_scope": "clips:read" }
  },
  "request_id": "req_..."
}

HTTP	`code`	Meaning
401	`missing_api_key`	No API key was provided
401	`invalid_api_key`	Key not recognized or malformed
401	`key_revoked`	Key or its app has been revoked/disabled
401	`key_expired`	Key has passed its expiry
401	`invalid_signature`	HMAC request signature failed (signed mode)
403	`ip_not_allowed`	Source IP not in the app allowlist
403	`insufficient_scope`	Key lacks the required scope
429	`rate_limited`	Per-key rate limit exceeded (see `Retry-After`)
400	`validation_error`	Invalid request body or parameters
404	`not_found`	Resource does not exist in your organization
409	`idempotency_conflict`	Duplicate in-flight/idempotent request
501	`not_implemented`	Endpoint reserved but not available yet (e.g. highlight generate)
500	`internal_error`	Unexpected server error

Always branch on error.code, not the human-readable message (which may change).
Include request_id when contacting support.