Erros
O SIP Caller usa códigos de status HTTP padrão para indicar se uma solicitação foi bem-sucedida. Os códigos na faixa 2xx indicam sucesso, os códigos na faixa 4xx indicam um problema com a solicitação (por exemplo, um campo ausente ou um registro que não existe), e os códigos na faixa 5xx indicam um problema do lado do SIP Caller.
Formato da resposta de erro
As respostas de erro têm um corpo JSON que segue o padrão Problem Details:
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
"title": "One or more errors occurred.",
"status": 404,
"detail": "Campaign with id '01a0dedd-b9a2-729d-8e0a-4e3ad9197aea' not found",
"instance": "/v1/accounts/ACCOUNT_ID/campaigns/01a0dedd-b9a2-729d-8e0a-4e3ad9197aea",
"traceId": "0HN6QKQ1B2F3G:00000001"
}| Campo | Descrição |
|---|---|
type | Uma URL que identifica o tipo de erro, com base no código de status HTTP. |
title | Um resumo curto e genérico do erro. |
status | O código de status HTTP. |
detail | Uma explicação legível deste erro específico. Não está presente nos erros de validação. |
instance | O caminho da solicitação que causou o erro. |
traceId | Um identificador único da solicitação. Inclua-o ao entrar em contato com o suporte sobre um erro. |
errors | Somente nos erros 400 e 409: a lista de mensagens para cada campo inválido, conforme descrito abaixo. |
As mensagens de detail e errors têm o objetivo de ajudar os desenvolvedores a entender o problema. Não as interprete no seu código, pois o texto pode mudar: use o código de status HTTP em vez disso.
Erros de validação
Quando um ou mais campos da solicitação são inválidos, a API retorna um erro 400 Bad Request com um objeto errors. Cada chave é o nome de um campo inválido (usando pontos para os campos aninhados), e cada valor é a lista de problemas encontrados:
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"instance": "/v1/accounts/ACCOUNT_ID/campaigns",
"errors": {
"name": ["Value must not be empty."],
"maxAttempts": ["Value must be between 1 and 9."]
},
"traceId": "0HN6QKQ1B2F3G:00000002"
}Todos os campos inválidos são informados de uma só vez, para que você possa corrigi-los em uma única etapa. Os erros nos parâmetros de query string filter, sort e range são informados da mesma forma, sob essas chaves.
Códigos de status HTTP
| Código | Significado |
|---|---|
200 OK | A solicitação foi bem-sucedida. |
201 Created | O recurso foi criado. A resposta contém o novo recurso. |
400 Bad Request | A solicitação é inválida: falta um campo obrigatório, um valor tem o formato errado ou está fora do intervalo, ou o JSON está malformado. Consulte o campo errors ou detail. |
401 Unauthorized | Não foi fornecida uma chave de API válida. Consulte Autenticação. |
403 Forbidden | A chave de API não tem permissão para realizar a operação. |
404 Not Found | O recurso não existe, ou não pertence à conta. |
408 Request Timeout | O corpo da solicitação foi enviado muito lentamente. |
409 Conflict | A solicitação entra em conflito com o estado atual do recurso. Por exemplo, um nome que deve ser único já está em uso, ou um recurso não pode ser excluído porque está sendo usado. |
412 Precondition Failed | O recurso foi modificado por outra pessoa desde a última vez que você o leu. Consulte Atualizações simultâneas abaixo. |
413 Payload Too Large | O corpo da solicitação excede o tamanho máximo de 20 MB. |
429 Too Many Requests | Foram enviadas muitas solicitações em pouco tempo. Consulte Limites de taxa. |
500 Internal Server Error | Algo deu errado do lado do SIP Caller. Nossa equipe é notificada automaticamente. Você pode repetir a solicitação mais tarde. |
Atualizações simultâneas
Para evitar que alterações se percam quando o mesmo recurso é editado ao mesmo tempo por diferentes usuários ou aplicações, as solicitações de atualização (por exemplo Atualizar uma campanha) exigem um campo lastUpdatedAt. Ele deve conter o valor updatedAt do recurso, conforme retornado na última vez em que você o obteve, criou ou editou.
Se o recurso tiver sido modificado nesse meio-tempo, seu valor updatedAt não coincide mais, e a atualização é rejeitada com um erro 412 Precondition Failed:
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.13",
"title": "One or more errors occurred.",
"status": 412,
"detail": "Update aborted to prevent 'lost update' problem; retry with correct 'lastUpdatedAt' value",
"instance": "/v1/accounts/ACCOUNT_ID/blackLists/BLACK_LIST_ID",
"traceId": "0HN6QKQ1B2F3G:00000003"
}Quando receber esse erro, obtenha o recurso novamente, aplique suas alterações à versão mais recente, e envie a atualização com o novo valor de lastUpdatedAt.
Tratamento de erros
Recomendamos a seguinte abordagem na sua integração:
- Erros
4xx(exceto429): não repita a mesma solicitação, pois ela falhará novamente. Registre a resposta, incluindo otraceId, e corrija a solicitação. - Erros
429: aguarde o número de segundos indicado no cabeçalhoRetry-After, e tente novamente. - Erros
5xxe erros de rede: tente novamente com um backoff exponencial (por exemplo, após 1, 2, 4 e 8 segundos). Tenha cuidado ao repetir solicitações que criam recursos ou adicionam números, pois a primeira tentativa pode ter sido bem-sucedida antes do erro: verifique o estado atual antes de tentar novamente.
Resposta de erro
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"instance": "/v1/accounts/ACCOUNT_ID/blackLists",
"errors": {
"name": [
"Value must not be empty."
]
},
"traceId": "0HN6QKQ1B2F3G:00000002"
}
