Tratamento de Erros

A API SplitPay segue o padrão RFC 7807 (Problem Details for HTTP APIs) para retornar erros de forma consistente e estruturada.

Estrutura de Erro

Todos os erros seguem este formato:

{
  "type": "https://api.splitgames.com.br/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Os dados fornecidos são inválidos.",
  "instance": "/api/v1/transactions/create",
  "errors": [
    {
      "field": "amount",
      "message": "O valor deve ser maior que zero."
    }
  ],
  "traceId": "00-abc123-def456-00"
}

Campos

type

URI que identifica o tipo de erro

title

Título curto e legível do erro

status

Código HTTP do erro

detail

Explicação detalhada do erro

instance

URI da requisição que gerou o erro

errors

Array de erros específicos (opcional, usado em validações)

traceId

ID de rastreamento para debugging (inclua ao reportar problemas)

Códigos de Status HTTP

400

Bad Request

Requisição inválida. Verifique os parâmetros enviados. O campo errors conterá detalhes sobre os campos inválidos.

401

Unauthorized

Credenciais ausentes ou inválidas. Verifique se os headers X-Client-Id e X-API-Key estão corretos.

403

Forbidden

Acesso negado. Suas credenciais são válidas, mas você não tem permissão para acessar este recurso.

404

Not Found

Recurso não encontrado. Verifique se o ID da transação ou endpoint está correto.

429

Too Many Requests

Limite de requisições excedido. Aguarde antes de fazer novas requisições. Veja o header Retry-After para saber quando tentar novamente.

500

Internal Server Error

Erro interno do servidor. Se o problema persistir, entre em contato com o suporte incluindo o traceId.

Exemplo de Tratamento

JavaScript

try {
  const response = await fetch('https://api.splitgames.com.br/api/v1/transactions/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Client-Id': 'seu-client-id',
      'X-API-Key': 'sua-api-key'
    },
    body: JSON.stringify({
      paymentMethod: 'PIX',
      amount: 500,
      // ...
    })
  });

  if (!response.ok) {
    const error = await response.json();
    console.error('Erro:', error.title);
    console.error('Detalhes:', error.detail);
    console.error('TraceId:', error.traceId);
    
    if (error.errors) {
      error.errors.forEach(err => {
        console.error(`Campo ${err.field}: ${err.message}`);
      });
    }
    
    throw new Error(error.detail);
  }

  const data = await response.json();
  console.log('Sucesso:', data);
} catch (error) {
  console.error('Falha na requisição:', error);
}