Skip to main content

​
Formato de resposta

Respostas de sucesso retornam: 
{
  "data": { ... }
}
Respostas de erro retornam: 
{
  "error": {
    "code": "validation_error",
    "message": "O campo 'amount' deve ser maior ou igual a 100.",
    "field": "amount"
  }
}
CampoTipoDescrição
codestringCódigo do erro (estável, use para lógica)
messagestringDescrição legível (pode mudar, não use para lógica)
fieldstring?Campo relacionado ao erro (quando aplicável)

​
Códigos HTTP

StatusDescriçãoQuando
200SucessoRequisição processada com sucesso
201CriadoRecurso criado com sucesso
400Bad RequestDados inválidos ou malformados
401UnauthorizedAPI key ausente, inválida ou revogada
403ForbiddenSem permissão (scope insuficiente ou ação não permitida)
404Not FoundRecurso não encontrado
409ConflictConflito de estado (ex: tentar simular transação já completa)
422Unprocessable EntityValidação falhou
429Too Many RequestsRate limit excedido
500Internal Server ErrorErro interno do servidor

​
Códigos de erro comuns

CódigoHTTPDescrição
unauthorized401Autenticação falhou
forbidden403Sem permissão para esta ação
not_found404Recurso não encontrado
validation_error422Dados de entrada inválidos
conflict409Conflito de estado
rate_limit429Limite de requisições excedido
internal_error500Erro interno

​
Tratamento com SDK

O SDK lança erros tipados para facilitar o tratamento: 
import { PagozzError, AuthenticationError, ValidationError, RateLimitError } from '@pagozz/sdk';

try {
  await pagozz.links.create({ name: '' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Key inválida ou revogada (401)
  } else if (error instanceof ValidationError) {
    // Dados inválidos (422)
    console.log(error.field); // campo com erro
  } else if (error instanceof RateLimitError) {
    // Rate limit excedido (429) — SDK retenta automaticamente
  } else if (error instanceof PagozzError) {
    // Outro erro da API
    console.log(error.code, error.message, error.status);
  }
}

​
Convenção snake_case

Todos os campos de request e response usam snake_case: 
{
  "value_mode": "fixed",
  "payment_methods": ["pix"],
  "success_redirect_url": "https://meusite.com/obrigado",
  "created_at": "2026-03-10T10:30:00Z"
}