Catálogo de Erros (WIP)

Visão geral

Todos os erros retornam um corpo padronizado:

{
  "code": "INVALID_PAYLOAD",
  "message": "One or more fields in the request payload are invalid",
  "details": [
    { "field": "partner.type", "code": "INVALID_VALUE", "message": "Field is invalid" }
  ],
  "timestamp": "2026-10-02T12:00:00Z"
}

Estrutura da resposta de erro

Campo	Tipo	Descrição
`code`	string	Código de erro em UPPER_SNAKE_CASE
`message`	string	Descrição legível do erro
`details`	array	Lista de erros por campo. Retornado somente em 400; omitido nos demais códigos
`details[].field`	string	Qual campo contém erro
`details[].code`	string	Qual erro do campo específico
`details[].message`	string	Descrição legível deste erro
`timestamp`	string	ISO-8601

Códigos de erro por jornada

Jornada	HTTP	Código de Erro	Significado
Validação	`400`	`INVALID_PAYLOAD`	Campo(s) inválido(s); `details[]` lista cada erro
Validação	`413`	`PAYLOAD_TOO_LARGE`	Documento acima do limite (5 MB)
Validação	`415`	`UNSUPPORTED_MEDIA_TYPE`	`Content-Type` não suportado
Onboarding	`404`	`ONBOARDING_NOT_FOUND`	Onboarding não encontrado
Onboarding	`409`	`IDEMPOTENCY_PAYLOAD_MISMATCH`	Chave de idempotência reutilizada com payload diferente
Onboarding	`409`	`RESOURCE_BUSY`	Recurso em processamento concorrente — tente novamente
Onboarding	`422`	`DOCUMENT_ALREADY_REGISTERED`	Documento já registrado no marketplace
Onboarding	`422`	`ONBOARDING_ALREADY_PROCESSING`	Onboarding já em processamento
Onboarding	`422`	`INVALID_STATE`	Operação não permitida no estado atual
Onboarding	`422`	`INVALID_ONBOARDING_DATA`	Dados de onboarding inválidos
Onboarding	`422`	`MISSING_REQUIRED_DOCUMENTS`	Documentos obrigatórios não enviados
Onboarding	`422`	`INVALID_DOCUMENT`	Documento enviado inválido
Gestão do Profile	`404`	`PROFILE_NOT_FOUND`	Profile não encontrado
Gestão do Profile	`422`	`INVALID_STATE`	Operação não permitida no estado atual
Gestão do Profile	`422`	`INVALID_FIELD_FOR_PROFILE_TYPE`	Campo não aplicável ao tipo (PF/PJ)
Gestão do Profile	`429`	`VALIDATION_ATTEMPT_LIMIT_EXCEEDED`	Limite de tentativas de validação de conta excedido
Gestão de Conta	`404`	`ACCOUNT_NOT_FOUND`	Conta não encontrada
Funds Out	`404`	`TRANSFER_NOT_FOUND`	Transferência não encontrada
Funds Out	`422`	`TRANSFER_ACCOUNT_NOT_VALIDATED`	Conta externa ainda não validada
Shared	`503`	`SERVICE_TEMPORARILY_UNAVAILABLE`	Serviço temporariamente indisponível