Respostas das Requisições

Formato de Resposta

Todas as respostas são entregues no formato JSON contendo um status success indicando sucesso (true) ou falha (false), uma string message contendo um texto (string), um objeto chamado data, além de um objeto adicional chamado meta com metadados de paginação e pode ter diferentes formatos conforme o endpoint utilizado.

Leia a documentação de Paginação para entender melhor como ela funciona.

Exemplo de uso

Requisição inicial para buscar empresas (primeira página de resultados):

GET /v1/companies?cursor=

Exemplo de resposta com sucesso

{
  "success": true,
  "message": "OK",
  "data": [
    {
      "id": 12345,
      "name": "Empresa XPTO"
      // ... outros campos
    }
  ],
  "meta": {
    "cursor": {
      "current": null,
      "prev": null,
      "next": "eyJpZCI6MTQ3MTMxMTEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
      "count": null
    }
  }
}

Exemplo de resposta com erro

{
    "success": false,
    "message": "Not Found"
}

Códigos de Status HTTP

A tabela abaixo apresenta os possíveis códigos de status que podem ser retornados após uma requisição à API:

Código de retorno	Mensagem (`message`)	Descrição / Comentário
200	OK	A requisição foi bem-sucedida.
201	Created	A requisição foi bem-sucedida e um novo recurso foi criado.
202	Accepted	Utilizado para tarefas assíncronas. A solicitação foi aceita para processamento, mas o resultado será obtido em outra chamada de API.
204	No Content	A requisição foi bem-sucedida, mas não tem nenhum conteúdo para retornar. Geralmente resposta para requisições DELETE.
400	Bad Request	A requisição é inválida. A causa do erro é descrita no corpo da resposta.
401	Unauthorized	Autenticação falhou.
402	Payment Required	A conta vinculada ao token do usuário está expirada. Entre em contato com os administradores da conta.
403	Forbidden	O usuário não tem acesso ao recurso. Verifique o nível do usuário (Consultor ou Gestor).
404	Not Found	O recurso solicitado não existe.
422	Unprocessable Entity	Problema com os dados enviados.
429	Too Many Requests	Limite de requisições excedido. A API aceita 120 requisições a cada 30 segundos.
500	Internal Server Error	Erro interno no servidor, não conseguimos processar a sua solicitação.
503	Temporarily Unavailable	Sistema temporariamente indisponível, geralmente por manutenção.
524	A Timeout Occurred	Tempo limite excedido. Por padrão, o gateway da API cancela requisições acima de 60 segundos.