Skip to main content

​
Problemas de Autenticação

Sintomas: Todas as requisições retornam este erroCausas Possíveis:
  • Cabeçalho X-ORGANIZATION-SLUG ausente ou incorreto
  • Usuário não tem acesso à organização
  • Slug da organização incorreto
Solução:
// Verifique se o slug está correto (minúsculas, hífens)
const ORG_SLUG = 'minha-organizacao'; // ✓ Correto
const ORG_SLUG = 'MinhaOrganizacao';  // ✗ Errado
const ORG_SLUG = 'minha_organizacao'; // ✗ Errado

// Certifique-se de que o cabeçalho está definido
headers: {
  'X-ORGANIZATION-SLUG': ORG_SLUG,
  // ...
}
Sintomas: Mutations são bloqueadas, queries funcionamSolução:
  1. Vá para Configurações → Chaves de API
  2. Gere uma nova chave com escopo read_write
  3. Atualize sua aplicação com a nova chave
  4. Revogue a chave antiga
Sintomas: Requisições retornam 429 após uso intensoSolução Imediata:
const response = await fetch(url, options);

if (response.status === 429) {
  const reset = parseInt(response.headers.get('X-RateLimit-Reset'));
  const waitMs = (reset * 1000) - Date.now();

  console.log(`Aguardando ${Math.ceil(waitMs / 1000)}s para reset...`);
  await sleep(waitMs);

  // Tentar novamente
  return fetch(url, options);
}
Solução de Longo Prazo:
  • Implemente agrupamento de requisições em lotes
  • Use backoff exponencial
  • Cache resultados quando possível

​
Problemas de Validação

Sintomas: Importações de transações sempre falhamCausa: Parâmetro accountId ausenteSolução:
# ✓ Correto
mutation CreateImport($data: [JSON!]!, $accountId: ID!) {
  importCreate(input: {
    data: $data
    entityType: TRANSACTION
    accountId: $accountId  # ← Obrigatório para transações
    dryRun: false
  }) { ... }
}
Sintomas: Registros falham com categoria ausenteCausa: Categoria referenciada não existeSolução Opção 1 - Criar categoria primeiro:
mutation CreateCategory {
  categoryCreate(input: {
    name: "Despesas de Escritório"
    code: "DESP-ESC"
    categoryType: expense
  }) {
    category { id }
  }
}
Solução Opção 2 - Usar criação automática:
{
  "category_name": "Despesas de Escritório",
  // A categoria será criada automaticamente
}
Criação automática está disponível para: categorias, centros de custo, departamentos
Sintomas: Erros de validação em campos de dataCausa: Formato de data incorretoSolução:
// ✓ Correto - formato ISO 8601
transaction_date: "2025-10-01"
due_date: "2025-10-15"

// ✗ Errado
transaction_date: "01/10/2025"  // Formato brasileiro
transaction_date: "10-01-2025"  // Formato americano
due_date: "2025/10/15"          // Barras ao invés de hífens

​
Problemas de Importação

Sintomas: Status nunca muda de pending para processingCausas Possíveis:
  • Fila de jobs sobrecarregada (raro)
  • Erro ao iniciar processamento
Solução:
  1. Aguarde 5 minutos
  2. Se ainda em pending, verifique se há errorMessage
  3. Contate suporte se persistir: [email protected]
Sintomas: Status completed, mas recordsCreated é 0Causa: Todos os registros falharam na validaçãoSolução:
query GetImportDetails($id: ID!) {
  import(id: $id) {
    recordsTotal
    recordsCreated
    recordsFailed

    # Buscar detalhes das falhas
    failedRecords {
      rowNumber
      errorMessage
      data
    }
  }
}
Sintomas: Alguns registros falham sem motivo óbvioDepuração:
  1. Execute dry run primeiro para capturar erros
  2. Verifique warnings - podem indicar problemas
  3. Revise logs de falhas após importação
  4. Isole registros com falha e teste individualmente

​
Problemas de Performance

Sintomas: Importações demoram mais de 1 minuto para 100 registrosOtimizações:
  • Reduza o tamanho do lote: 500-1000 registros por importação
  • Minimize lookups: Use IDs ao invés de nomes quando possível
  • Evite horários de pico: Importe fora do horário comercial
  • Pre-crie associações: Crie categorias/centros de custo antes
Sintomas: Requisições falham com timeoutSolução:
// Aumente o timeout para importações grandes
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 60000); // 60s

try {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers,
    body: JSON.stringify(payload),
    signal: controller.signal
  });

  clearTimeout(timeoutId);
  return await response.json();
} catch (error) {
  if (error.name === 'AbortError') {
    console.error('Requisição timeout após 60s');
  }
  throw error;
}

​
Problemas de Dados

Sintomas: Valores salvos com centavos incorretosCausa: Formato de número incorretoSolução:
// ✓ Correto - string com ponto decimal
amount: "150.50"
amount: "1000.00"

// ✗ Errado
amount: 150.50        // Número (pode perder precisão)
amount: "150,50"      // Vírgula (formato brasileiro)
amount: "R$ 150,50"   // Com símbolo de moeda
Sintomas: Registros duplicados são criadosCausa: Campo de identificação único ausenteSolução:
// Use external_id ou reference_number para prevenir duplicatas
{
  transaction_date: "2025-10-01",
  amount: "150.00",
  description: "Pagamento",
  external_id: "TXN-2025-10-001",  // ← Chave única
  reference_number: "REF-12345"     // ← Alternativa
}

​
Ferramentas de Depuração

​
GraphiQL Playground

Use o playground interativo para testar requisições:

GraphiQL

Ambiente interativo para testar queries e mutations

​
Verificar Headers de Rate Limit

const response = await fetch(endpoint, options);

console.log('Rate Limit Info:');
console.log('  Limit:', response.headers.get('X-RateLimit-Limit'));
console.log('  Remaining:', response.headers.get('X-RateLimit-Remaining'));
console.log('  Reset:', new Date(
  parseInt(response.headers.get('X-RateLimit-Reset')) * 1000
).toLocaleString());

​
Dry Run para Depuração

Sempre use dry run para depurar problemas de validação: 
mutation DebugValidation($data: [JSON!]!) {
  importCreate(input: {
    data: $data
    entityType: TRANSACTION
    dryRun: true
  }) {
    validRecords
    invalidRecords
    previewData
    warnings
  }
}

​
Quando Contatar Suporte

Contate [email protected] se:
  • Importações ficam travadas por mais de 10 minutos
  • Você suspeita de um bug na API
  • Precisa de aumento no limite de taxa
  • Tem perguntas sobre casos de uso específicos
Inclua na mensagem:
  • ID da organização
  • ID da importação (se aplicável)
  • Timestamp do problema
  • Passos para reproduzir
  • Código de exemplo (se possível)

​
Recursos Adicionais

Tratamento de Erros

Referência completa de erros

Fluxo de Importação

Processo completo de importação