Error: insufficient_permissions

Qué significa

La clave API está autenticada correctamente, pero no tiene el scope necesario para realizar la operación solicitada.

Envelope de ejemplo

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_permissions",
    "message": "Esta clave API no tiene permiso para crear facturas. Se requiere el scope 'invoices.write'.",
    "doc_url": "https://docs.emitia.co/errors/insufficient_permissions",
    "request_id": "req_01HX…"
  }
}

HTTP status: 403 Forbidden

Causas frecuentes

Causa	Solución
La clave tiene scope read y estás ejecutando una mutación	Crea una clave con scope invoices.write o *
Estás accediendo a datos de otro tenant	Cada clave solo puede ver su propio tenant
La clave de prueba tiene restricciones de scope	Crea una clave nueva sin restricciones de scope

Cómo resolverlo

1. Revisa el scope de tu clave en el dashboard → API Keys.
2. Para operaciones de escritura, necesitas invoices.write o * (todos los scopes).
3. Si no puedes cambiar la clave existente, crea una nueva con los scopes necesarios.

Scopes disponibles

Scope	Operaciones permitidas
read	Solo operaciones GET
invoices.write	Crear facturas, notas crédito y notas débito
webhooks.manage	Crear y gestionar webhook endpoints
*	Todos los scopes (recomendado para integración completa)

Ver también

• Inicio rápido