Códigos de resposta
Ao integrar-se com a API da Singular, todas as respostas retornam códigos de status HTTP 200, exigindo a validação do campo 'status' do corpo da resposta para determinar o sucesso ('ok') ou a falha ('erro').
O payload da resposta inclui um campo'reason' que fornece informações detalhadas sobre o erro quando o status é'error'.
Recomendações
- Implementar um mecanismo de repetição de retrocesso exponencial com tentativas máximas configuráveis, excluindo erros não repetíveis, como parâmetros inválidos.
- Manter a ordem dos pedidos durante as tentativas para garantir a consistência dos dados.
- Para uma depuração e monitorização adequadas, registe todos os pedidos falhados, incluindo parâmetros originais, mensagens de erro, identificadores de dispositivos e carimbos de data/hora. Acompanhe as tentativas de repetição e implemente um sistema de notificação para falhas críticas. O formato de resposta a erros segue uma estrutura JSON consistente com campos de estado e motivo.
Esta estratégia abrangente de tratamento de erros garante uma integração robusta da API, mantendo a exatidão dos dados e fornecendo uma visibilidade clara de potenciais problemas.
Sucesso
O seguinte identifica uma resposta bem sucedida da API a um pedido.
| Resposta HTTP | |
|---|---|
|
O 200 - ok sem qualquer erro ou motivo no corpo da resposta significa que o pedido foi enviado para a fila de espera para processamento. Resposta: |
Erros
O seguinte identifica as mensagens de erro que a API pode devolver numa resposta a um pedido.
| Resposta HTTP | |
|---|---|
|
O código de resposta de erro 200 - com a "razão" de "argumento em falta: {param}". Este erro só ocorrerá para parâmetros específicos e não para todos os parâmetros necessários. Se o parâmetro estiver em falta ou o valor estiver em falta, pode receber um erro de argumento em falta. O erro deve ser resolvido e o pedido reenviado. Resposta: |
|
O código de resposta de erro 200 - com a "razão" de "plataforma inválida: {platform}". Isto significa que o valor da plataforma não é válido. O erro deve ser resolvido e o pedido reenviado. Resposta: |
|
O código de resposta de erro 200 - com o "motivo" de "não foi fornecido um ID de dispositivo". O identificador do dispositivo não foi incluído no pedido. O erro deve ser resolvido e o pedido reenviado. Resposta: |
|
O código de resposta de erro 200 com "motivo" de "plataforma: {platform} deve ter um parâmetro {identifier}". O erro significa que a plataforma especificada não tem o identificador de dispositivo correto. O erro deve ser resolvido e o pedido reenviado. Resposta: |
|
Os pedidos devem ser repetidos se não for recebido um 200 - ok. |