Referência HTTP e Códigos de Status

Documentação completa de todos os endpoints e códigos de resposta da API.

URL Base

https://api.arkangelai.com/v1

Endpoints Disponíveis

Chat

Método	Endpoint	Descrição
POST	/chat	Enviar mensagem e receber resposta
POST	/chat/stream	Enviar mensagem com streaming de resposta

Conversas

Método	Endpoint	Descrição
GET	/conversations	Listar conversas
GET	/conversations/:id	Obter uma conversa
PATCH	/conversations/:id	Atualizar conversa
DELETE	/conversations/:id	Excluir conversa
GET	/conversations/search	Pesquisar conversas
GET	/conversations/:id/export	Exportar conversa

Arquivos

Método	Endpoint	Descrição
POST	/files	Fazer upload de arquivo
GET	/files	Listar arquivos
GET	/files/:id	Obter informações do arquivo
DELETE	/files/:id	Excluir arquivo

Uso

Método	Endpoint	Descrição
GET	/usage	Obter métricas de uso
GET	/usage/limits	Verificar limites
GET	/usage/endpoints	Uso por endpoint
GET	/usage/errors	Histórico de erros
GET	/usage/export	Exportar dados de uso
POST	/usage/alerts	Configurar alertas

Limites de Taxa

Todos os endpoints da API aplicam limites de taxa para garantir uso justo e estabilidade da plataforma. Os limites são aplicados por usuário (identificado pela sua chave de API) usando uma janela deslizante.

Limites Padrão

Endpoint	Limite	Janela
POST /chat	20 solicitações	1 minuto
POST /chat/stream	20 solicitações	1 minuto
GET /conversations, GET /conversations/:id	60 solicitações	1 minuto
PATCH /conversations/:id, DELETE /conversations/:id	30 solicitações	1 minuto
POST /files	30 solicitações	1 minuto
GET /files, GET /files/:id, DELETE /files/:id	60 solicitações	1 minuto
GET /conversations/:id/export, GET /usage/export	5 solicitações	1 minuto
GET /usage, GET /usage/*	60 solicitações	1 minuto

Resposta de Limite de Taxa

Quando você excede um limite, a API retorna um status 429 Too Many Requests com os seguintes cabeçalhos:

Cabeçalho	Descrição
X-RateLimit-Limit	Número máximo de solicitações permitidas na janela atual
X-RateLimit-Remaining	Solicitações restantes na janela atual
X-RateLimit-Reset	Timestamp Unix de quando a janela reinicia
Retry-After	Segundos a aguardar antes de tentar novamente

Aguarde a duração especificada em Retry-After antes de enviar outra solicitação.

Códigos de Status HTTP

Respostas de Sucesso (2xx)

Código	Nome	Descrição
200	OK	Solicitação bem-sucedida
201	Created	Recurso criado com sucesso
204	No Content	Solicitação bem-sucedida sem conteúdo de resposta

Erros do Cliente (4xx)

Código	Nome	Descrição
400	Bad Request	Solicitação malformada ou parâmetros inválidos
401	Unauthorized	Chave de API ausente ou inválida
403	Forbidden	Sem permissão para acessar o recurso
404	Not Found	Recurso não encontrado
409	Conflict	Conflito com o estado atual
422	Unprocessable Entity	Dados válidos mas não processáveis
429	Too Many Requests	Limite de solicitações excedido

Erros do Servidor (5xx)

Código	Nome	Descrição
500	Internal Server Error	Erro interno do servidor
502	Bad Gateway	Erro de gateway
503	Service Unavailable	Serviço temporariamente indisponível
504	Gateway Timeout	Tempo limite da solicitação

Formato de Erros

Todas as respostas de erro seguem este formato:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "message": "A chave de API fornecida é inválida",
    "param": "authorization",
    "request_id": "req_abc123"
  }
}

Campos do Erro

Campo	Tipo	Descrição
type	string	Categoria do erro
code	string	Código específico do erro
message	string	Descrição legível do erro
param	string	Parâmetro que causou o erro (se aplicável)
request_id	string	ID único para rastreamento

Tipos de Erro

Tipo	Descrição
invalid_request_error	Parâmetros inválidos ou ausentes
authentication_error	Problemas de autenticação
permission_error	Permissões ausentes
not_found_error	Recurso não existe
rate_limit_error	Limite de solicitações excedido
api_error	Erro interno da API

Códigos de Erro Comuns

Autenticação

Código	Descrição
invalid_api_key	Chave de API inválida
missing_api_key	Nenhuma chave de API fornecida
api_key_revoked	Chave de API revogada
api_key_expired	Chave de API expirada

Solicitações

Código	Descrição
invalid_message	Mensagem vazia ou inválida
message_too_long	Mensagem excede limite de caracteres
invalid_conversation_id	ID de conversa inválido
invalid_file_id	ID de arquivo inválido

Arquivos

Código	Descrição
invalid_file_type	Tipo de arquivo não suportado
file_too_large	Arquivo excede tamanho máximo
file_processing_failed	Erro ao processar arquivo

Limites

Código	Descrição
rate_limit_exceeded	Limite de solicitações por segundo
daily_limit_exceeded	Limite diário atingido
monthly_limit_exceeded	Limite mensal atingido
storage_limit_exceeded	Limite de armazenamento atingido

Cabeçalhos de Resposta

Cabeçalho	Descrição
X-Request-Id	ID único da solicitação
X-RateLimit-Limit	Limite de solicitações por janela
X-RateLimit-Remaining	Solicitações restantes
X-RateLimit-Reset	Timestamp de reinício do limite
Retry-After	Segundos a aguardar (em 429)

Exemplo de Tratamento de Erros

async function handleApiResponse(response) {
  if (response.ok) {
    return response.json();
  }

  const error = await response.json();

  switch (response.status) {
    case 401:
      throw new Error('Autenticação falhou. Verifique sua chave de API.');
    case 429:
      const retryAfter = response.headers.get('Retry-After');
      throw new Error(`Limite excedido. Tente novamente em ${retryAfter} segundos.`);
    case 500:
      throw new Error('Erro do servidor. Tente novamente mais tarde.');
    default:
      throw new Error(error.error?.message || 'Erro desconhecido');
  }
}

Próximos Passos

• Suporte - Entre em contato com nossa equipe para ajuda
• Autenticação - Voltar ao guia de autenticação