# Códigos de erro

> Todos os códigos de erro públicos do OonCore, agrupados por origem, com status HTTP e significado.

Faça branching por `code`, nunca pelo texto da mensagem. O envelope está em [Erros](/docs/backend/erros).

## Runtime local

| Código | Significado |
|---|---|
| `LOCAL_RUNTIME_ENV_INVALID` | Modo local fora de `NODE_ENV=development` |
| `LOCAL_RUNTIME_PLATFORM_IDENTITY` | Identidade de plataforma/Kubernetes presente |
| `LOCAL_RUNTIME_BIND_FORBIDDEN` | Bind fora de loopback |
| `LOCAL_HOST_FORBIDDEN` / `LOCAL_ORIGIN_FORBIDDEN` | Acesso de rede recusado |
| `LOCAL_PROXY_FORBIDDEN` | Tentativa de proxy no modo local |
| `LOCAL_BOOTSTRAP_INVALID` | Código ausente, reutilizado ou expirado |
| `LOCAL_SESSION_INVALID` | Cookie ausente, inválido ou expirado |
| `LOCAL_SESSION_EXPIRED` | Prazo local encerrado |
| `LOCAL_CSRF_INVALID` | Mutação sem prova CSRF |
| `LOCAL_ROLE_NOT_DECLARED` | Perfil fora do manifesto |
| `LOCAL_OPERATION_NOT_SUPPORTED` | Recurso exclusivo da plataforma |

## Registro e manifestos

| Código | Status | Significado |
|---|---:|---|
| `OON_ROUTE_REGISTRATION_INVALID` | — | Assinatura inválida em `router.private` |
| `OON_BACKEND_CWD_INVALID` | — | `cwd` do backend inválido |
| `OON_DOMAIN_MANIFEST_INVALID` | 422 | `central.domain.json` inválido (`issues[]`) |

## Domínio e dados

| Código | Status | Significado |
|---|---:|---|
| `DomainRuleError` (código da regra) | 422 | Validação declarativa ou fórmula inválida |
| `TARGET_TENANT_REQUIRED` | 400 | Operação administrativa sem tenant-alvo |
| `DATABASE_POOL_BUSY` | 503 | Espera por conexão expirou |
| `DATABASE_OPERATION_TIMEOUT` | 504 | Tempo de execução excedido |

## Acesso

| Código | Status | Significado |
|---|---:|---|
| `RBAC_PRIVILEGE_ESCALATION_DENIED` | 403 | Atribuição de perfil com permissões que o ator não tem |
| `CENTRAL_ACCESS_COMMAND_REQUIRED` | — | Alteração deve ser feita na Central (convites pela Central) |
| `APP_ROLE_CATALOG_UNAVAILABLE` | — | Catálogo de perfis ausente ou inválido |
| `RBAC_IDENTITY_PROVIDER_ERROR` | 502 | Central respondeu 5xx |
| `RBAC_IDENTITY_PROVIDER_UNREACHABLE` | — | Central sem resposta |
| `INTEGRATION_ROLE_NOT_ALLOWED` | 403 | Token de integração com perfil administrativo fora das condições |
| `APP_LAUNCH_TOKEN_MISSING` | 502 | Troca de abertura sem sessão |

## Arquivos e uso

| Código | Status |
|---|---:|
| `FILE_TENANT_REQUIRED` | 400 |
| `FILE_NOT_FOUND` | 404 |
| `FILE_TOO_LARGE` | 413 |
| `FILE_NAME_INVALID` | 422 |
| `FILE_STORAGE_UNAVAILABLE` | 503 |
| `USAGE_METRIC_INVALID` / `USAGE_QUANTITY_INVALID` | 422 |
| `USAGE_LIMIT_REACHED` | 423 |

## Capabilities

| Código | Retry | Significado |
|---|:---:|---|
| `PDF_RENDERING_INVALID_INPUT` | não | HTML vazio ou acima do limite |
| `PDF_RENDERING_INVALID_OPTIONS` | não | Opção inválida |
| `PDF_RENDERING_UNAVAILABLE` | sim | Capability não resolvida |
| `PDF_RENDERING_CREDENTIAL_UNAVAILABLE` | sim | Credencial interna não injetada |
| `PDF_RENDERING_IMPLEMENTATION_ERROR` | sim | Falha da implementação |
| `PDF_RENDERING_TIMEOUT` | sim | Prazo ou cancelamento |
| `PDF_RENDERING_SATURATED` | sim | Concorrência excedida |
| `PDF_RENDERING_TRANSPORT_ERROR` | sim | Falha de transporte |
| `PDF_RENDERING_INVALID_OUTPUT` | sim | Saída inválida |
| `EMAIL_CAPABILITY_NOT_DECLARED` | — | E-mail sem declaração no manifesto |
| `EMAIL_*` | — | Demais erros sanitizados de e-mail |
| `SECRETS_USE_FAILED` | — | Erro no callback de `secrets.use` |

## Publicação

| Código | Significado |
|---|---|
| `IMAGE_MODULE_NOT_FOUND` | Import ausente na imagem (arquivo fora de `backend/` ou dependência de dev) |

Fonte: https://sdk.oonapps.com/docs/referencia/codigos-de-erro