Contrato de respostas e erros da Admin API

Este ficheiro completa o contrato de resposta de todos os endpoints na Referência de endpoints. Consulte a linha do endpoint para o corpo de sucesso e as tabelas abaixo para todos os corpos de insucesso comuns ou específicos. Por predefinição, os erros usam várias estruturas de compatibilidade; os clientes podem optar por um envelope universal.

Envelope de erro estruturado opcional

Envie este cabeçalho de pedido para qualquer endpoint:

X-Error-Format: envelope

A comparação remove espaços nas extremidades e não distingue maiúsculas de minúsculas. Com esse valor exato, todas as respostas JSON com estado 400 ou superior são convertidas em:

ErrorEnvelope = {
  error: {
    code: string,
    message: string,
    details: Record<string, unknown>,
    requestId: string
  }
}

Exemplo de conversão de um corpo de validação predefinido:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid request",
    "details": {
      "fields": {
        "name": ["String must contain at least 1 character(s)"]
      }
    },
    "requestId": "integration-42"
  }
}

As regras de conversão são exatas:

• validationErrors passa a details.fields e code passa a VALIDATION_FAILED, mesmo quando o corpo predefinido também tinha um código de domínio.
• É mantido um code predefinido no nível superior quando não existem campos de validação.
• As outras propriedades de nível superior, exceto error, message, validationErrors e code, passam para details; por exemplo, limit da exportação de relatórios passa a details.limit.
• Um error de texto no nível superior passa a message. Se não existir, é usado o valor de recurso do estado.
• Os códigos de recurso são AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 e outros 4xx não classificados), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) e INTERNAL_ERROR (outros 5xx, incluindo 503).
• requestId é o cabeçalho de resposta X-Request-Id exato. Um ID de pedido fornecido pelo cliente só é usado quando corresponde a [A-Za-z0-9._:-]{1,128} após remover espaços nas extremidades; caso contrário, o servidor gera um UUID.

Esta transformação não altera o estado nem os cabeçalhos não relacionados com o corpo. Também se aplica a repetições idempotentes segundo o cabeçalho X-Error-Format do pedido de repetição. As respostas de sucesso binárias permanecem binárias; os respetivos erros JSON recebem o envelope. As tabelas restantes mostram os corpos predefinidos; as regras acima produzem o outro corpo de resposta possível para cada linha.

Notação das respostas

ValidationError = {
  validationErrors: Record<string, string[]>,
  code?: string
}

CodedError = {
  error: string,
  code: string,
  // a route may add fields explicitly listed below
}

PlainError = { error: string }

error e o texto da mensagem de validação são descritivos, não discriminadores programáticos estáveis. Distinga casos por code quando presente. A validação do pedido devolve 422 ValidationError; a validação de um objeto completo pode produzir { "validationErrors": {} } quando não é identificado um campo individual. JSON inválido e falhas inesperadas devolvem o 500 PlainError global abaixo.

Todos os exemplos JSON apresentam a estrutura exata do corpo. O texto apresentado como <message> é a mensagem de validação ou operação devolvida e é uma cadeia JSON, não um valor literal entre parênteses angulares.

Ordem de processamento dos pedidos

Os pedidos são processados por esta ordem:

1. configuração e autenticação dos tokens de espaço de trabalho;
2. política do anfitrião e limites de pedidos por token/espaço de trabalho;
3. filtragem dos direitos atuais;
4. para cada alteração, validação/reserva de idempotência;
5. verificações de âmbito do endpoint, validação do pedido e operação solicitada.

Assim, uma alteração com um token válido, mas com âmbitos insuficientes, continua a exigir o envio de Idempotency-Key. Uma resposta concluída de alteração 403, 404, 409 ou 422 pode ser repetida para a mesma chave/pedido.

Respostas de autenticação, política e limitação de pedidos

Estas respostas podem ocorrer em qualquer endpoint /v2/admin registado antes do processamento específico do endpoint.

O acesso à API está incluído em todos os planos. Desativar a definição adminApiEnabled do anfitrião do espaço de trabalho devolve 404; perder um direito de função adicional remove apenas os âmbitos afetados. A recusa de âmbito resultante usa a resposta abaixo, não um fluxo de renovação de tokens.

Âmbito, idempotência, análise, propriedade e falhas inesperadas

Os IDs nos caminhos de recursos têm de ser números positivos. Um :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId ou :localUserId não positivo ou não numérico devolve 422 ValidationError, não 400.

Erros de locais e gestão de potência

Erros dos carregadores

mapChargerErrors() é usado na criação/atualização do carregador, credenciais, definições de conector, listagem pública, resolução de conteúdo QR, alteração/recarregamento de configuração, início de firmware, nos quatro comandos básicos e no pedido de agendamento composto.

As operações de leitura simples devolvem apenas as respostas comuns 401/403/404/429/500/503 e a validação 422 da consulta/caminho. A eliminação do carregador pode devolver o 500 PlainError comum se falhar sem uma resposta de erro mais específica.

Erros dos relatórios

A exportação bem-sucedida é binária; todos os erros de exportação continuam a ser JSON.

Erros das tarifas

Erros dos perfis de carregamento

Erros do domínio de utilizadores

Os erros de validação de utilizadores que identificam um campo usam ValidationError e code; os restantes usam CodedError. Todos os casos de recursos em falta usam a resposta comum RESOURCE_NOT_FOUND, que não revela a existência de recursos.

POST /users/invitations também pode devolver o 403 INSUFFICIENT_SCOPE comum após analisar o corpo se faltar users:access, ou se tiver sido fornecido RFID e faltar users:rfid. Os endpoints de utilizadores locais indicam todos os âmbitos obrigatórios na Referência de endpoints.

Os códigos de erro de utilizador aplicam-se da seguinte forma:

Todos os resultados de propriedade e recursos em falta nestas famílias, incluindo um email não registado em POST /users, usam o corpo comum 404 RESOURCE_NOT_FOUND.

Respostas sem corpo e de repetição

Uma resposta 204 bem-sucedida não tem corpo. Isto aplica-se a todas as eliminações documentadas que indicam 204 empty. Uma repetição idempotente concluída define Idempotency-Replayed: true e usa o estado/corpo guardado; para 204, a resposta HTTP continua sem corpo. A API nunca devolve um objeto JSON de sucesso para uma operação 204 documentada.