Códigos e respostas de erro comuns
Os erros na API do OneDrive serão retornados por meio de códigos de status HTTP padrão, bem como um objeto de resposta de erro JSON. Os códigos de status HTTP a seguir devem ser esperados.
| Código de status | Mensagem de status | Descrição |
|---|---|---|
| 400 | Solicitação Incorreta (Bad Request) | Não é possível processar a solicitação porque está incorreta ou mal feita. |
| 401 | Não Autorizado (Unauthorized) | 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 (Not Found) | O recurso solicitado não existe. |
| 405 | Método Não Permitido (Method Not Allowed) | O método HTTP na solicitação não é permitido no recurso. |
| 406 | Não Aceitável (Not Acceptable) | Esse serviço não dá suporte ao formato solicitado no cabeçalho Accept. |
| 409 | Conflito | O estado atual está em conflito com o que a solicitação espera. Por exemplo, a pasta pai especificada não existe. |
| 410 | Sumiu (Gone) | O recurso solicitado não está mais disponível no servidor. |
| 411 | Comprimento Solicitado (Length Required) | É necessário um cabeçalho Content-Length na solicitação. |
| 412 | Falha na Pré-condição (Precondition Failed) | 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 Solicitação Muito Grande (Request Entity Too Large) | O tamanho da solicitação excede o limite máximo. |
| 415 | Tipo de Mídia Não Suportado (Unsupported Media Type) | O tipo de conteúdo da solicitação é um formato sem suporte pelo serviço. |
| 416 | Intervalo Solicitado Não Satisfatório (Requested Range Not Satisfiable) | O intervalo de bytes especificado é inválido ou está indisponível. |
| 422 | Entidade Não Processável (Unprocessable Entity) | Não é possível processar a solicitação porque ela está semanticamente incorreta. |
| 429 | Muitos Pedidos (Too Many Requests) | O aplicativo cliente foi restringido e não deve tentar repetir a solicitação antes de determinado intervalo de tempo. |
| 500 | Erro Interno do Servidor (Internal Server Error) | Ocorreu um erro interno do servidor ao processar a solicitação. |
| 501 | Não Implementado (Not Implemented) | O recurso solicitado não foi implementado. |
| 503 | Serviço Indisponível | O serviço está temporariamente indisponível. Você pode repetir a solicitação depois de um atraso. Pode haver um cabeçalho Retry-After |
| 507 | Armazenamento Insuficiente (Insufficient Storage) | A cota máxima de armazenamento foi atingida. |
| 509 | Limite de Largura de Banda Excedido | Seu aplicativo foi limitado por exceder o limite máximo de largura de banda. O aplicativo pode tentar a solicitação novamente depois de decorrido algum tempo. |
A resposta de erro é um único objeto JSON que contém uma propriedade única chamada error. Esse 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 retornado. Aqui está um exemplo de um corpo de erro JSON completo.
{
"error": {
"code": "invalidRange",
"message": "Uploaded fragment overlaps with existing data.",
"innererror": {
"code": "fragmentOverlap"
}
}
}
A propriedade de código
A propriedade code contém um dos 15 valores possíveis. Os aplicativos devem estar preparados para lidar com qualquer um desses erros.
| Código | Descrição |
|---|---|
| accessDenied | O chamador não tem permissão para executar a ação. |
| activityLimitReached | O aplicativo ou o usuário foi restringido. |
| generalException | Ocorreu um erro não especificado. |
| invalidRange | O intervalo de bytes especificado é inválido ou está indisponível. |
| invalidRequest | A solicitação está incorreta ou foi mal formada. |
| itemNotFound | Não foi possível localizar o recurso. |
| malwareDetected | Malware detectado no recurso solicitado. |
| nameAlreadyExists | O nome do item especificado já existe. |
| notAllowed | A ação não é permitida pelo sistema. |
| notSupported | A solicitação não tem suporte do sistema. |
| resourceModified | O recurso em atualização foi alterado desde que o chamador o leu pela última vez, geralmente uma incompatibilidade de eTag. |
| resyncRequired | O token delta não é mais válido e o aplicativo deve redefinir o estado de sincronização. |
| serviceNotAvailable | 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 |
| quotaLimitReached | O usuário atingiu seu limite de cota. |
| unauthenticated | O chamador não está autenticado. |
O objeto innererror pode conter repetidamente mais objetos innererror com códigos de erro adicionais, mais específicos. Ao lidar com um erro, os aplicativos devem percorrer todos os códigos de erro disponíveis e usar o mais detalhado que consigam entender. Alguns dos códigos mais detalhados estão listados na parte inferior desta página.
Para verificar se um objeto de erro é um erro que você está esperando, execute um loop sobre os objetos innererror procurando os códigos de erro que você espera. Por exemplo:
public bool IsError(string expectedErrorCode)
{
OneDriveInnerError errorCode = this.Error;
while (null != errorCode)
{
if (errorCode.Code == expectedErrorCode)
return true;
errorCode = errorCode.InnerError;
}
return false;
}
Confira um exemplo completo de como lidar com erros adequadamente em Tratamento de códigos de erro do OneDrive.
A propriedade message na raiz contém uma mensagem de erro destinada ao desenvolvedor. As mensagens de erro não são localizadas e não devem ser exibidas diretamente para o usuário. Ao tratar de erros, seu código não deve desviar dos valores message porque eles podem mudar a qualquer momento e geralmente contêm informações dinâmicas específicas para a solicitação com falha. Você só deve escrever códigos contra códigos de erro retornados nas propriedades code.
Confira mais informações sobre o recurso retornado na resposta de erro no tópico Tipo de recurso de erro.
Códigos de erro detalhados
A seguir estão alguns erros adicionais que seu aplicativo pode encontrar nos objetos aninhados innererror. Os aplicativos não são obrigados a tratar deles, mas podem, se quiserem. O serviço pode adicionar novos códigos de erro ou parar de retornar os antigos a qualquer hora; portanto, é importante que todos os aplicativos consigam tratar dos 15 básicos acima.
| Código | Descrição |
|---|---|
| accessRestricted | Acesso restrito ao proprietário do item. |
| cannotSnapshotTree | Falha ao obter um instantâneo delta consistente. Tente novamente mais tarde. |
| childItemCountExceeded | Limite máximo do número de itens filhos atingido. |
| entityTagDoesNotMatch | ETag não corresponde ao valor do item atual. |
| fragmentLengthMismatch | O tamanho total declarado para esse fragmento é diferente do da sessão de carregamento. |
| fragmentOutOfOrder | O fragmento carregado está fora da ordem. |
| fragmentOverlap | Fragmento carregado sobrepõe-se a dados existentes. |
| invalidAcceptType | Tipo de aceitação inválido. |
| invalidParameterFormat | Formato de parâmetro inválido. |
| invalidPath | O nome contém caracteres inválidos. |
| invalidQueryOption | Opção de consulta inválida. |
| invalidStartIndex | Índice de início inválido. |
| lockMismatch | O token de bloqueio não corresponde ao bloqueio existente. |
| lockNotFoundOrAlreadyExpired | Não há atualmente nenhum bloqueio expirado no item. |
| lockOwnerMismatch | A ID do proprietário do bloqueio não corresponde à ID fornecida. |
| malformedEntityTag | O Cabeçalho ETag está mal feito. ETags devem ser cadeias de caracteres entre aspas. |
| maxDocumentCountExceeded | Atingido o limite máximo do número de documentos. |
| maxFileSizeExceeded | Tamanho máximo do arquivo excedido. |
| maxFolderCountExceeded | Atingido o limite máximo do número de pastas. |
| maxFragmentLengthExceeded | Tamanho máximo do arquivo excedido. |
| maxItemCountExceeded | Limite máximo do número de itens atingido. |
| maxQueryLengthExceeded | Comprimento máximo de consulta excedido. |
| maxStreamSizeExceeded | Tamanho máximo de fluxo excedido. |
| parameterIsTooLong | Parâmetro excede o comprimento máximo. |
| parameterIsTooSmall | Parâmetro é menor que o valor mínimo. |
| pathIsTooLong | O caminho excede o comprimento máximo. |
| pathTooDeep | Atingido o limite de profundidade da hierarquia de pastas. |
| propertyNotUpdateable | Propriedade não atualizável. |
| resyncApplyDifferences | Nova sincronização necessária. Substitua todos os itens locais com a versão do servidor (incluindo exclusões) se você tiver certeza de que o serviço estava atualizado com suas alterações locais quando você sincronizou pela última vez. Carregar alterações locais que o servidor não conhece. |
| resyncRequired | Nova sincronização é necessária. |
| resyncUploadDifferences | Nova sincronização necessária. Carregue os itens locais que o serviço não retornou e carregue os arquivos que diferem da versão do servidor (mantendo ambas as cópias se você não tiver certeza de qual é a mais atual). |
| serviceNotAvailable | O servidor não consegue processar a solicitação atual. |
| serviceReadOnly | O recurso é temporariamente somente leitura. |
| throttledRequest | Muitos pedidos. |
| tooManyResultsRequested | Muitos resultados solicitados. |
| tooManyTermsInQuery | Muitos termos na consulta. |
| totalAffectedItemCountExceeded | Operação não permitida porque o número de itens afetados excede o limite. |
| truncationNotAllowed | O truncamento de dados não é permitido. |
| uploadSessionFailed | Falha na sessão de carregamento. |
| uploadSessionIncomplete | Sessão de carregamento incompleta. |
| uploadSessionNotFound | Sessão de carregamento não encontrada. |
| virusSuspicious | Este documento é suspeito e pode conter um vírus. |
| zeroOrFewerResultsRequested | Nenhum ou poucos resultados solicitados. |