Códigos de resposta da API de referências
Aplica-se a: Partner Center | Referências do Partner Center
Funções apropriadas: Administrador de indicações | Usuário de indicações
As APIs REST de Referências do Partner Center retornam um objeto JSON que contém um código de status. Este código indica se sua solicitação foi bem-sucedida ou por que ela falhou.
Respostas de sucesso
Um código de status 2xx indica que a solicitação do cliente foi recebida, compreendida e aceita com sucesso. Os seguintes códigos de status 2xx indicam uma resposta bem-sucedida:
- 200: Sucesso confirmado
- 201: Recurso criado
- 202: Aceito
- 204: Sem conteúdo a ser devolvido
Respostas de erro
Qualquer resposta com um código de status 4xx ou 5xx inclui uma mensagem de erro com detalhes sobre as condições de erro desse código.
A tabela a seguir lista e descreve os códigos de status HTTP que podem ser retornados para cenários de erro.
| Código de status | Mensagem de status | Descrição |
|---|---|---|
| 400 | Solicitação incorreta | Não é possível processar a solicitação porque ela está malformada ou incorreta. |
| 401 | Não Autorizado | As informações de autenticação necessárias estão ausentes ou não são válidas para o recurso. |
| 403 | Proibido | Acesso negado ao recurso solicitado. O usuário pode não ter permissão suficiente. |
| 404 | Não encontrado | O recurso solicitado não existe. |
| 405 | Método Não Permitido | O método HTTP na solicitação não é permitido no recurso. |
| 406 | Não Aceitável | Este serviço não é compatível com o formato solicitado no cabeçalho Accept. |
| 409 | Conflito | O estado atual entra em conflito com o que a solicitação espera. Por exemplo, a pasta pai especificada pode não existir. |
| 410 | Não existe mais | O recurso solicitado não está mais disponível no servidor. |
| 411 | Comprimento Obrigatório | Um cabeçalho Content-Length é necessário na solicitação. |
| 412 | Falha na Pré-condição | Uma pré-condição fornecida na solicitação (como um cabeçalho if-match) não corresponde ao estado atual do recurso. |
| 413 | A entidade da solicitação é muito grande | O tamanho da solicitação excede o limite máximo. |
| 415 | Tipo de Mídia Sem Suporte | O tipo de conteúdo da solicitação é um formato ao qual o serviço não dá suporte. |
| 416 | Intervalo Solicitado Não Satisfatório | O intervalo de bytes especificado é inválido ou não está disponível. |
| 422 | Entidade Não Processável | Não é possível processar a solicitação porque ela está semanticamente incorreta. |
| 423 | Bloqueado | O recurso que está sendo acessado está bloqueado. |
| 429 | Número Excessivo de Solicitações | O aplicativo cliente é limitado e não deve tentar repetir a solicitação por algum tempo. |
| 500 | Erro interno do servidor | Ocorreu um erro de servidor interno ao processar a solicitação. |
| 501 | Não Implementado | O recurso solicitado não está implementado. |
| 503 | Serviço indisponível | O serviço está temporariamente indisponível para manutenção ou está sobrecarregado. Será possível repetir a solicitação após um atraso, cuja duração pode ser especificada no cabeçalho Retry-After. |
| 504 | Tempo Limite do Gateway | O servidor, enquanto atuava como um proxy, não recebeu uma resposta oportuna do servidor upstream que precisava acessar na tentativa de concluir a solicitação. Pode ocorrer junto com 503. |
| 507 | Armazenamento Insuficiente | Atingiu a cota máxima de armazenamento. |
| 509 | Limite de Largura de Banda Excedido | O aplicativo cliente foi limitado por exceder o limite máximo de largura de banda. Seu aplicativo pode repetir a solicitação novamente após algum tempo. |
Tipo de recurso de erro
A resposta de erro é um único objeto JSON que contém uma única propriedade denominada erro. Esse objeto inclui todos os detalhes do erro. É possível usar as informações retornadas aqui em vez de ou além do código de status HTTP.
A tabela e os exemplos de código a seguir descrevem o esquema de uma resposta de erro.
| Nome | Tipo | Descrição |
|---|---|---|
| code | string | Sempre retornado. Indica o tipo de erro que ocorreu. Não nulo. |
| message | string | Sempre retornado. Descreve o erro em detalhes e fornece mais informações de depuração. Não nulo, não vazio. O comprimento máximo é de 1.024 caracteres. |
| innerError | objeto | Opcional. Ocorreu outro objeto de erro com informações mais específicas sobre o erro. |
| innerError.code | Cadeia de caracteres numérica | Sempre retornado, se innerError não for nulo. Fornece informações de código de erro mais específicas sob o valor do código de erro superior. |
| innerError.message | string | Sempre retornado, se innerError não for nulo. Fornece uma mensagem de erro mais específica na cadeia de caracteres de mensagem de erro superior. |
| innerError.details | matriz objeto | Opcional. Contém mais detalhes sobre o erro. Útil principalmente em erros de validação de entrada. |
| destino | string | Opcional. O alvo no qual o erro se originou. |
Exemplo de resposta de erro
{
"error": {
"code": "unauthenticated",
"message": "The caller is not authenticated.",
"innerError": {
"code": "99902",
"message": "Request not authenticated",
"details": null
}
}
}
Outro exemplo com o objeto innerError.details preenchido:
{
"error": {
"code": "invalidRequest",
"message": "The request is malformed or incorrect.",
"innerError": {
"code": "99901",
"message": "InvalidInput",
"details": [
{
"InvalidReferralForCoSellConversion": [
"If PartnerLed referral has no solution it cannot be converted to co-sell referral"
]
}
]
}
}
}
Propriedade do código
A propriedade code contém um dos seguintes valores possíveis. Seus aplicativos devem estar preparados para lidar com qualquer um desses erros.
| Código | Código de status HTTP | Descrição |
|---|---|---|
| invalidRequest | 400 | A solicitação está malformada ou incorreta. |
| não autenticado | 401 | O chamador não está autenticado. |
| accessDenied | 403 | O chamador não tem permissão para executar a ação. |
| itemNotFound | 404 | O recurso não pôde ser encontrado. |
| resourceModified | 409 | O recurso que está sendo atualizado foi alterado desde a última vez que o chamador o leu, geralmente uma incompatibilidade de eTag. |
| preconditionFailed | 412 | Uma pré-condição fornecida na solicitação (como um cabeçalho if-match) não corresponde ao estado atual do recurso. |
| generalException | 500 | Ocorreu um erro não especificado. |
| serviceNotAvailable | 503 | O serviço não está disponível. Repita a solicitação após um atraso. Pode haver um cabeçalho Retry-After. |
Propriedade de mensagem
A propriedade message na raiz contém uma mensagem de erro destinada ao desenvolvedor para leitura. As mensagens de erro não são localizadas e não devem ser exibidas diretamente para o usuário. Seu código não deve verificar message os valores apenas porque eles podem ser alterados a qualquer momento e geralmente contêm informações dinâmicas específicas para a solicitação com falha. Você deve codificar os códigos de erro retornados nas code propriedades e, em seguida, combiná-los com o texto da mensagem.
Objeto InnerError
O innererror objeto pode conter recursivamente mais innererror objetos com códigos de erro mais específicos. O aplicativo cliente, ao lidar com um erro, deve percorrer todos os códigos de erro disponíveis e usar o mais detalhado que eles entendem.
Há mais alguns erros que seu aplicativo pode encontrar nos objetos aninhados innererror . Os aplicativos não são obrigados a lidar com esses erros, mas podem fazer isso se quiserem. O serviço pode adicionar novos códigos de erro ou parar de retornar os antigos a qualquer momento, por isso é importante que todos os aplicativos sejam capazes de lidar com os [códigos de erro básicos].
Códigos do Erro
Veja a seguir os códigos de erro retornados pelas APIs:
| Status HTTP | Código de erro HTTP | Código do erro | Descrição |
|---|---|---|---|
| BadRequest | 400 | 99901 | Entrada inválida |
| Não Autorizado | 401 | 99902 | Unauthorized access |
| BadRequest | 400 | 99903 | Entrada ausente |
| NotFound | 404 | 99,904 | Recurso não encontrado |
| InternalServerError | 500 | 99905 | Erro não especificado |
| TooManyRequests | 429 | 99906 | Número excessivo de solicitações |
| InternalServerError | 500 | 99907 | Erro interno transitório |
| BadRequest | 400 | 99908 | A propriedade não pode ser atualizada |
| BadRequest | 400 | 99909 | A propriedade não é anulável |
| PreconditionFailed | 412 | 99910 | O valor da etiqueta não corresponde |
| BadRequest | 400 | 99911 | Status de referência inválido para convidar |
| BadRequest | 400 | 99912 | Solução com o tipo 'nome' é necessária |
| Proibido | 403 | 99913 | Organização não incluída na lista de permissões para criar recursos |
| Proibido | 403 | 99914 | Organização não incluída na lista de permissões para participar de compromissos de venda conjunta |
| InternalServerError | 500 | 99915 | Falha na execução de solicitações internas |
| Conflito | 409 | 99917 | Recurso já modificado por meio de outra solicitação |
| PreConditionFailed | 412 | 99918 | Uma pré-condição fornecida na solicitação (como um cabeçalho if-match) não corresponde ao estado atual do recurso. |
| BadRequest | 400 | 99919 | Qualificação de referência inválida para atualização |
| InternalServerError | 500 | 99999 | Exceção geral durante o processamento da solicitação |