Visão geral da API: URLs, versões e erros - Supercosmos for Platforms

URLs base

Ambiente	URL base
Produção	`https://api.mippo.io`
Sandbox	`https://sandbox-api.mippo.io`

Todos os endpoints do Supercosmos for Platforms ficam sob /v1/laas/. Os endpoints de gestão de conta ficam sob /laas/partner/.

Rate limits

Escopo	Limite
Por API key	100 requests / minuto
Envios de KYC	20 / minuto por key
Inicializações de transação	50 / minuto por key

Exceder um limite retorna 429 Too Many Requests com um header Retry-After.

Formato de erros

Todos os erros seguem um envelope consistente:

{
  "success": false,
  "error": {
    "code": "SCREAMING_SNAKE_CASE",
    "message": "Human-readable description.",
    "details": {}
  }
}

Códigos de erro comuns

Código	HTTP	Significado
`INVALID_API_KEY`	401	Key ausente, malformada ou revogada
`PARTNER_SUSPENDED`	403	A sua conta de desenvolvedor foi suspensa
`KYC_REJECTED`	422	Cliente reprovado na análise de compliance
`KYC_TOKEN_EXPIRED`	422	O token de KYC tem mais de 24h
`INVALID_WALLET_ADDRESS`	422	Endereço de wallet falhou na validação do checksum
`TRANSACTION_NOT_FOUND`	404	O ID da transação não existe
`MFA_INVALID_CODE`	422	Código TOTP incorreto ou expirado
`RATE_LIMIT_EXCEEDED`	429	Requisições em excesso
`INTERNAL_ERROR`	500	Erro do lado da Supercosmos — entre em contato com o suporte

Idempotência

Para endpoints POST, envie um header Idempotency-Key (qualquer string única, por exemplo um UUID) para poder repetir requests com segurança em caso de falhas de rede. Requests duplicados com a mesma key retornam a response em cache.

curl -X POST https://api.mippo.io/v1/laas/transactions/initiate \
  -H "X-Mippo-API-Key: sk_live_..." \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{ ... }'