Compartilhar via

Status e códigos de erro

As operações da API REST para o Armazenamento do Azure retornam códigos de status HTTP padrão, conforme definido nas Definições de Código de Status HTTP/1.1.

As operações de API também podem retornar informações detalhadas de erro que o serviço define. Essas informações de erro são retornadas no corpo da resposta.

O corpo da resposta de erro segue o formato básico mostrado aqui. O code elemento indica a cadeia de caracteres do código de erro, enquanto o message elemento indica a cadeia de caracteres da mensagem de erro.

<?xml version="1.0" encoding="utf-8"?>  
<Error>  
  <Code>string-value</Code>  
  <Message>string-value</Message>  
</Error>

Para a versão 2017-07-29 e posterior, as operações de API com falha também retornam a cadeia de caracteres de código de erro do Armazenamento do Azure em um cabeçalho de resposta.

Cabeçalho de resposta Descrição
x-ms-error-code Um valor que indica a cadeia de caracteres do código de erro.

Uma resposta de erro específica também pode incluir informações detalhadas sobre o erro para fornecer mais informações ao desenvolvedor. Por exemplo, a resposta de erro a seguir indica um parâmetro de consulta inválido especificado no URI da solicitação e fornece informações adicionais sobre o nome e o valor do parâmetro inválido e o motivo do erro.

<?xml version="1.0" encoding="utf-8"?>  
<Error>  
  <Code>InvalidQueryParameterValue</Code>  
  <Message>Value for one of the query parameters specified in the request URI is invalid.</Message>  
  <QueryParameterName>popreceipt</QueryParameterName>  
  <QueryParameterValue>33537277-6a52-4a2b-b4eb-0f905051827b</QueryParameterValue>  
  <Reason>invalid receipt format</Reason>  
</Error>

Para a versão 2024-08-04 e posterior, a resposta de erro incluirá informações detalhadas sobre o erro quando o tipo de recurso assinado da SAS da conta não corresponder ao recurso que está sendo acessado. Por exemplo, a resposta de erro a seguir indica que o tipo de recurso assinado 'o' é necessário para executar a operação.

<?xml version="1.0" encoding="utf-8"?>
<Error>
  <Code>AuthorizationResourceTypeMismatch</Code>
  <Message>This request is not authorized to perform this operation using this resource type. RequestId:42a48a49-201e-0092-3770-a7ea70000000 Time:2024-05-16T09:04:16.3226200Z</Message>
  <ExtendedErrorDetail>SignedResourceTypes 'o' is required to perform this operation.</ExtendedErrorDetail>
</Error>

A lista de artigos a seguir fornece coleções de códigos de erro que podem ser úteis:

Copiar resposta de erro da API

A resposta de erro para as APIs de cópia segue o mesmo formato mencionado anteriormente. O corpo da resposta de erro contém o code elemento para a cadeia de caracteres do código de erro e o message elemento que indica a cadeia de caracteres da mensagem de erro.

Para as versões 2024-02-04 e posteriores, a resposta de erro poderá incluir um erro detalhado se a operação Copiar falhar devido a um problema com a origem da cópia, desde que a falha da origem retorne essas informações. A resposta pode incluir CopySourceStatusCode a indicação do código de status da operação de origem de cópia, CopySourceErrorCode especificando a x-ms-error-code resposta de erro retornada na fonte de cópia e CopySourceErrorMessage indicando a mensagem de erro correspondente.

<?xml version="1.0" encoding="utf-8"?>  
<Error>  
  <Code>CannotVerifyCopySource</Code>  
  <Message> The specified blob doesn’t exist.
      RequestId:de1e2279-b01e-0000-5f26-5c4741000000
      Time:2023-03-21T18:52:10.1018932Z</Message>
  <CopySourceStatusCode> 404 </CopySourceStatusCode>
  <CopySourceErrorCode> BlobNotFound </CopySourceErrorCode>
  <CopySourceErrorMessage> The specified blob doesn’t exist </CopySourceErrorMessage> 
</Error>

Para versões 2024-02-04 e posteriores, o Armazenamento do Azure retornará o código-fonte de status de cópia e o código de erro no cabeçalho de resposta, se eles forem recebidos na falha de origem de cópia.

Cabeçalho de resposta Descrição
x-ms-copy-source-status-code Um valor que indica o código de status da falha de origem da cópia.
x-ms-copy-source-error-code Um valor que indica a cadeia de caracteres de código de erro retornada da falha de origem da cópia.

As seguintes APIs de cópia retornam estes detalhes -

Respostas de erro para o Armazenamento de Tabelas

As respostas de erro para o Armazenamento de Tabelas estão em conformidade com o formato de erro descrito na seção 19 da especificação OData. Informações detalhadas sobre o erro podem ser incluídas, mas a resposta do erro sempre está em conformidade com a OData especificação.

As respostas de erro em lote são semelhantes às respostas de erro padrão do Armazenamento de Tabelas. Para obter mais informações, consulte Executando transações de grupo de entidades.

Observação

JSON é o formato de carga recomendado para o Armazenamento de Tabelas. É o único formato com suporte para a versão 2015-12-11 e posterior.

O exemplo a seguir mostra o corpo do erro básico no formato JSON (versão 2013-08-15 e posterior):

{"odata.error":{"code":"ResourceNotFound","message":{"lang":"en-US","value":"The specified resource does not exist.\nRequestId:102a2b55-eb35-4254-9daf-854db78a47bd\nTime:2014-06-04T16:18:20.4307735Z"}}}

O exemplo a seguir mostra o corpo do erro básico no formato Atom (versões 2015-12-11 e anteriores):

<?xml version="1.0" encoding="utf-8"?>  
<error xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">  
  <code>ResourceNotFound</code>  
  <message xml:lang="en-US">The specified resource does not exist.  
RequestId:e288ba1e-f5dd-4014-9e09-f1263d223dec  
Time:2014-06-04T16:18:20.7088013Z</message>  
</error>

Consulte também

Solução de problemas de operações de API
Enumeração HttpStatusCode
Serviços de armazenamento REST