Especificações gerais das APIs

Os serviços RESTs seguem a seguinte convenção para o status HTTP

  • Sucesso:

    HttpCode 200
    Todo sucesso retornar 200 OK, os demais status 2XX não são utilizados.

  • Erros do cliente:

    HttpCode 400
    Qualquer erro que ocorrer devido a falhas provenientes de payload do cliente, deverá retornar 400 BAD_REQUEST, inclusive chamadas que não façam sentido no estado atual do dado, como erros de conflitos de chave, por exemplo.

    HttpCode 403
    Qualquer erro que ocorrer devido a falhas de autenticação ou autorização, retornará 403 FORBIDDEN.

    HttpCode 404
    O status 404 NOT_FOUND é utilizado conforme convenção aplicada em APIs REST.

  • Erros do serviço:

    HttpCode 500
    O status 500 INTERNAL_ERROR englobará todos os erros da família 5XX. Qualquer erro sistêmico é representado pelo código 500, inclusive BAD_GATEWAY, NOT_IMPLEMENTED, TIMEOUT, etc.

Como complemento aos códigos do HTTP, nas respostas diferentes de sucesso (HttpCode 200), também será retornado um JSON, com a estrutra abaixo.

{
    "code": "Um código interno de erro da aplicação, específico por microserviço",
    "message": "Uma mensagem explicando o que é o erro emitido",
    "details": "Descreve detalhes provenientes do erro, como a causa, se necessário. Campo opcional."
}

Exemplos de erros

  • Erro de POST devido a campos faltando ou inválidos na request:

    400 { 
       "code": "400001", 
       "message": "Invalid payload", 
       "details": "userPrincipalName should be filled; email should be a valid email;"
    }

  • Erro de POST devido a conflito de userPrincipalName já existente:

    400 { 
       "code": "400002", 
       "message": "Conflict", "details": "userPrincipalName already exists;" 
    }

  • Erro de falha de autenticação:

    403 { 
       "code": "403001", 
       "message": "Access denied" 
    }

  • Erro de registro não encontrado:

    404 { 
       "code": "404001", 
       "message": "Not found" 
    }

  • Erro interno:

    500 { 
       "code": "500001", 
       "message": "Internal server error" 
    }

  • Erro de gateway timeout:

    500 { 
       "code": "500002", 
       "message": "Timeout" 
    }

  • Erro de bad gateway:

    500 { 
       "code": "500003", 
       "message": "Internal server error" 
    }