Códigos de resposta da API de referências

2025-03-07

Aplica-se a: Partner Center | Referências do Partner Center

Funções apropriadas: Administrador de referências | Usuário de referências

As APIs REST do Partner Center Referrals retornam um objeto JSON que contém um código de status. Este código que indica se o seu pedido foi bem-sucedido ou porque 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: Não há conteúdo para devolver

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 para esse 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 estado	Mensagem de estado	Descrição
400	Pedido Incorreto	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	O 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 suporta o formato solicitado no cabeçalho Aceitar.
409	Conflito	O estado atual entra em conflito com o que o pedido espera. Por exemplo, a pasta pai especificada pode não existir.
410	Foi-se	O recurso pedido já não está disponível no servidor.
411	Comprimento Requerido	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	Entidade de Pedido Demasiado Grande	O tamanho da solicitação excede o limite máximo.
415	Tipo de mídia não suportado	O tipo de conteúdo da solicitação é um formato que o serviço não suporta.
416	Intervalo solicitado não satisfatório	O intervalo de bytes especificado é inválido ou indisponí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	Demasiados pedidos	O aplicativo cliente é limitado e não deve tentar repetir a solicitação por algum tempo.
500	Erro de Servidor Interno	Houve um erro interno do servidor durante o processamento da solicitação.
501	Não implementado	O recurso solicitado não foi implementado.
503	Serviço Indisponível	O serviço está temporariamente indisponível para manutenção ou está sobrecarregado. Você pode repetir a solicitação após um atraso, cujo comprimento pode ser especificado em um cabeçalho Retry-After .
504	Tempo limite do gateway	O servidor, embora atuasse como proxy, não recebeu uma resposta oportuna do servidor upstream que precisava acessar na tentativa de concluir a solicitação. Pode ocorrer juntamente com 503.
507	Armazenamento insuficiente	Atingida a quota máxima de armazenagem.
509	Limite de largura de banda excedido	A aplicação cliente foi restringida por exceder o limite máximo de largura de banda. Seu aplicativo pode repetir a solicitação novamente depois de algum tempo.

Tipo de erro de recurso

A resposta de erro é um único objeto JSON que contém uma única propriedade chamada error. Este objeto inclui todos os detalhes do erro. Você pode 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
código	string	Sempre retornado. Indica o tipo de erro que ocorreu. Não nulo.
mensagem	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.
erro interno	objeto	Opcional. Outro objeto de erro com informações mais específicas sobre o erro ocorreu.
innerError.code	cadeia numérica	Sempre retornado, se innerError não for nulo. Fornece informações mais específicas sobre o código de erro abaixo do valor principal do código de erro.
mensagemDeErroInterno	string	Sempre retornado, se innerError não for nulo. Fornece uma mensagem de erro mais específica sob a mensagem de erro principal.
detalhesDoErroInterno	objeto de array	Opcional. Contém mais detalhes sobre o erro. Principalmente útil em erros de validação de entrada.
destino	string	Opcional. O destino onde 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 de Código

A code propriedade 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 estado HTTP	Descrição
invalidRequest	400	O pedido está mal formado ou incorreto.
não autenticado	401	O chamador não é autenticado.
acessoNegado	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. Tente fazer a solicitação novamente após um atraso. Pode haver um cabeçalho Retry-After.

Propriedade de Mensagem

A message propriedade na raiz contém uma mensagem de erro destinada ao desenvolvedor ler. 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 os message 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. Deve verificar os códigos de erro retornados nas code propriedades e, em seguida, para mais detalhes, 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 o seu aplicativo pode encontrar nos objetos aninhados innererror. Os aplicativos não são necessários para lidar com esses erros, mas podem fazê-lo se desejarem. 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 de erro

A seguir estão os códigos de erro retornados pelas APIs:

HTTP Status	Código de erro HTTP	Código de erro	Descrição
Pedido Inválido	400	99901	Entrada inválida
Não autorizado	401	99902	Acesso não autorizado
Pedido Inválido	400	99903	Entrada em falta
Não encontrado	404	99904	Recurso não encontrado
InternalServerError	500	99905	Erro não especificado
Muitas Solicitações	429	99906	Demasiados pedidos
InternalServerError	500	99907	Erro interno transitório
Pedido Inválido	400	99908	A propriedade não é atualizável
Pedido Inválido	400	99909	A propriedade não é anulável
Pré-condição Falhada	412	99910	O valor de Etag não corresponde
Pedido Inválido	400	99911	Status de referência inválido para convidar
Pedido Inválido	400	99912	É necessária uma solução com o tipo 'nome'
Proibido	403	99913	Organização não autorizada a criar recurso
Proibido	403	99914	Organização não autorizada a participar de compromissos de co-venda
InternalServerError	500	99915	Falha na execução da solicitação interna
Conflito	409	99917	Recurso já modificado através de outro pedido
PréCondiçãoFalhou	412	99918	Uma pré-condição fornecida na solicitação (como um cabeçalho if-match) não corresponde ao estado atual do recurso.
Pedido Inválido	400	99919	Qualificação de referência inválida para atualização
Erro Interno do Servidor	500	99999	Exceção geral durante o processamento do pedido