Erros

A Partner API usa códigos de status HTTP padrão e corpos de resposta JSON para explicar por que uma solicitação falhou.

Formato da resposta de erro

A maioria dos erros da API retorna um corpo JSON com uma mensagem e, quando disponíveis, detalhes estruturados.

{
  "success": false,
  "message": "Request body.members[0].member_id is required"
}

Alguns endpoints de domínios específicos retornam um status e um motivo explícitos. Por exemplo, as falhas de controle de acesso incluem campos como reason, door_id, facility_id e event_id.

{
  "status": "failed",
  "reason": "device_offline",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "00000000-0000-0000-0000-000000000045"
}

Códigos de status

400 Bad Request

A solicitação está malformada ou faltam campos obrigatórios. Corrija a solicitação antes de tentar novamente.

401 Unauthorized

A autenticação falhou. Verifique se você está usando HTTP Basic Auth com sua chave secreta de API como nome de usuário e uma senha vazia.

403 Forbidden

A chave é válida, mas a operação não é permitida. As causas comuns incluem usar uma chave somente leitura em uma operação de gravação ou tentar acessar uma instalação em que sua integração não está ativada.

404 Not Found

O recurso solicitado não foi encontrado ou não está disponível para sua integração.

409 Conflict

A solicitação entra em conflito com o estado atual do recurso. No controle de acesso, isso pode incluir um Door/Gate Controller em modo de manutenção.

422 Unprocessable Entity

A solicitação é um JSON válido, mas falha na validação semântica. Corrija os dados antes de tentar novamente.

429 Too Many Requests

A integração excedeu o limite de taxa documentado. Tente novamente com recuo exponencial.

500 Internal Server Error

O Performance Hub não conseguiu concluir a solicitação devido a um erro interno. Tente novamente com recuo. Se o problema persistir, entre em contato com o suporte informando o endpoint, o carimbo de data/hora e o corpo da resposta.

503 Service Unavailable

Um serviço ou dispositivo dependente está indisponível. Em destravamentos do Door/Gate Controller, isso pode significar que o controlador está off-line.

504 Gateway Timeout

A operação excedeu o tempo limite. Em destravamentos do Door/Gate Controller, isso significa que o destravamento não foi confirmado dentro do tempo limite.

Falhas de Access Time Windows

A validação das janelas falha antes que o snapshot inválido seja gravado. As causas comuns que não devem ser repetidas incluem:

• Ausência de access_time_windows_revision quando access_time_windows está presente.
• Valores de época em string, em ponto flutuante ou provavelmente em milissegundos.
• Um fuso horário IANA inválido, um intervalo invertido, um external_id duplicado, blocos semanais sobrepostos ou um bloco noturno que não foi dividido.
• Um valor fora dos limites documentados de quantidade, tamanho ou duração.

Uma revisão repetida com conteúdo normalizado diferente é um 409 Conflict. Faça a reconciliação com o estado oficial mais recente e atribua uma revisão mais nova; não continue repetindo o par conflitante. Uma revisão mais antiga é relatada como um snapshot desatualizado ignorado, em vez de poder substituir um estado mais recente. Um scope_key desconhecido ou não mapeado falha de forma fechada para a autorização e deve ser tratado como um alerta de configuração.

Se a entrega exceder o tempo limite ou receber um 5xx transitório, repita exatamente o mesmo snapshot normalizado com a mesma revisão. Se a consulta à fonte de origem falhar, omita completamente o campo de janelas; nunca o substitua por uma matriz vazia.

Orientações sobre novas tentativas

Tente novamente estes com recuo exponencial limitado:

• 429
• 500
• 502
• 503
• 504

Não repita estes cegamente:

• 400
• 401
• 403
• 404
• 409
• 422

No controle de acesso, sempre trate respostas de tempo limite e off-line como destravamentos com falha, a menos que suas próprias regras de acesso e processos de segurança determinem o contrário.

Detalhes a incluir ao contatar o suporte

Ao entrar em contato com o suporte, inclua:

• Endpoint e método HTTP.
• Data e hora, com o fuso horário.
• ID da chave de parceiro, não a chave secreta.
• Identificador de instalação usado.
• ID do registro de origem no seu sistema.
• Status e corpo da resposta.
• event_id ou command_id, quando disponíveis.