Erros - Tartini

Formato de erro

Todos os erros seguem o mesmo formato JSON:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or expired API key"
}

Códigos HTTP

Código	Significado	Quando ocorre
`200`	Sucesso	Requisição processada corretamente
`401`	Não autorizado	API key ausente, inválida ou expirada
`403`	Proibido	Assinatura da empresa inativa
`422`	Entidade não processável	Corpo da requisição inválido
`500`	Erro interno	Erro inesperado no servidor

Erros de autenticação (401)

// API key ausente
{ "statusCode": 401, "error": "Unauthorized", "message": "Missing API key" }

// Formato inválido
{ "statusCode": 401, "error": "Unauthorized", "message": "Invalid API key format. Expected: Bearer <api_key>" }

// Chave inválida ou expirada
{ "statusCode": 401, "error": "Unauthorized", "message": "Invalid or expired API key" }

Erro de assinatura (403)

{
  "statusCode": 403,
  "error": "SubscriptionInactive",
  "message": "Sua assinatura não está ativa",
  "subscriptionStatus": "CANCELLED"
}

Erros de validação (422)

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": [
    "queryText must be a string",
    "scoreThreshold must not be greater than 1"
  ]
}

Tratamento de erros

async function ragRetrieve(query) {
  const response = await fetch('https://api-talk.saninternet.com/v1/api/rag/retrieve', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SANTALK_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      queryText: query,
      filters: { sourceTypes: ['document'], audience: 'ai_agent' },
      scoreThreshold: 0.7,
      returnMode: 'ai_generated_answer'
    })
  });

  if (!response.ok) {
    const error = await response.json();
    switch (response.status) {
      case 401: throw new Error(`Autenticação falhou: ${error.message}`);
      case 403: throw new Error(`Assinatura inativa: ${error.subscriptionStatus}`);
      case 422: throw new Error(`Validação: ${error.message}`);
      default: throw new Error(`Erro ${response.status}: ${error.message}`);
    }
  }

  return response.json();
}

import os
import requests

def rag_retrieve(query: str) -> dict:
    response = requests.post(
        'https://api-talk.saninternet.com/v1/api/rag/retrieve',
        headers={
            'Authorization': f'Bearer {os.environ["SANTALK_API_KEY"]}',
            'Content-Type': 'application/json'
        },
        json={
            'queryText': query,
            'filters': {'sourceTypes': ['document'], 'audience': 'ai_agent'},
            'scoreThreshold': 0.7,
            'returnMode': 'ai_generated_answer'
        }
    )

    if response.status_code == 401:
        raise Exception(f"Autenticação falhou: {response.json()['message']}")
    elif response.status_code == 403:
        raise Exception(f"Assinatura inativa: {response.json()['subscriptionStatus']}")

    response.raise_for_status()
    return response.json()