Tratamento de Erros ¶

Ao manusear uma requisição da API RESTful, se existir um erro na requisição do usuário ou se alguma coisa inesperada acontecer no servidor, você pode simplesmente lançar uma exceção para notificar o usuário de que algo deu errado. Se você puder identificar a causa do erro (ex., o recurso requisitado não existe), você deve considerar lançar uma exceção juntamente com um código de status HTTP adequado (ex., yii\web\NotFoundHttpException representa um código de status 404). O Yii enviará a resposta juntamente com o código e o texto do status HTTP correspondente. O Yii também incluirá a representação serializada da exceção no corpo da resposta. Por exemplo:

HTTP/1.1 404 Not Found
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

{
   "name": "Not Found Exception",
   "message": "The requested resource was not found.",
   "code": 0,
   "status": 404
}

A lista a seguir descrimina os códigos de status HTTP que são usados pelo framework REST do Yii:

• 200: OK. Tudo funcionou conforme o esperado;
• 201: Um recurso foi criado com êxito em resposta a uma requisição POST. O cabeçalho location contém a URL que aponta para o recurso recém-criado;
• 204: A requisição foi tratada com sucesso e a resposta não contém nenhum conteúdo no corpo (por exemplo uma requisição DELETE);
• 304: O recurso não foi modificado. Você pode usar a versão em cache;
• 400: Requisição malfeita. Isto pode ser causado por várias ações por parte do usuário, tais como o fornecimento de um JSON inválido no corpo da requisição, fornecendo parâmetros inválidos, etc;
• 401: Falha de autenticação;
• 403: O usuário autenticado não tem permissão para acessar o recurso da API solicitado;
• 404: O recurso requisitado não existe;
• 405: Método não permitido. Favor verificar o cabeçalho Allow para conhecer os métodos HTTP permitidos;
• 415: Tipo de mídia não suportada. O número de versão ou o content type requisitado são inválidos;
• 422: Falha na validação dos dados (na resposta a uma requisição POST, por exemplo). Por favor, verifique o corpo da resposta para visualizar a mensagem detalhada do erro;
• 429: Excesso de requisições. A requisição foi rejeitada devido a limitação de taxa;
• 500: Erro interno do servidor. Isto pode ser causado por erros internos do programa.

Customizando Resposta de Erro ¶

Às vezes você pode querer personalizar o formato de resposta de erro padrão. Por exemplo, em vez de confiar em usar diferentes status HTTP para indicar os diversos erros, você pode querer usar sempre o status 200 como resposta e colocar o código de status real como parte da estrutura JSON da resposta, como mostrado abaixo,

HTTP/1.1 200 OK
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

{
   "success": false,
   "data": {
       "name": "Not Found Exception",
       "message": "The requested resource was not found.",
       "code": 0,
       "status": 404
   }
}

Para atingir este objetivo, você pode responder o evento beforeSend do componente response na configuração da aplicação:

return [
   // ...
   'components' => [
       'response' => [
           'class' => 'yii\web\Response',
           'on beforeSend' => function ($event) {
               $response = $event->sender;
               if ($response->data !== null && Yii::$app->request->get('suppress_response_code')) {
                   $response->data = [
                       'success' => $response->isSuccessful,
                       'data' => $response->data,
                   ];
                   $response->statusCode = 200;
               }
           },
       ],
   ],
];

O código acima formatará a resposta (para ambas as respostas, bem-sucedidas e com falha) como explicado quando suppress_response_code é passado como um parâmetro GET.