Raiz - FlamPix Gateway API

This document provides a comprehensive list of all possible HTTP response codes and JSON bodies returned by the FlamPix Gateway API.

✅ Success Responses (2xx)

`200 OK`

The request was successfully processed.

Standard Success Response:

{
  "depositId": "c2a5dbd4-043a-4d4f-866e-8ddad4ed067c",
  "status": "awaiting_payment", // or 'paid', 'processing', etc.
  "amount": {
    "grossInCents": 15000,
    "feeInCents": 575,
    "netInCents": 14425
  },
  // ... other resource-specific fields
}

❌ Client Errors (4xx)

These errors are caused by invalid requests from the client.

`400 Bad Request`

The request body or parameters are invalid.

Error Message	Description
`X-Idempotency-Key é obrigatório`	Missing the idempotency header in POST requests.
`amountInCents deve ser um inteiro positivo`	The amount is invalid, zero, or negative.
`destinationAddress não pode coincidir com o split address`	You tried to send funds to the gateway's fee address.
`EUID inválido`	The provided EUID format is incorrect (must be 'EU' + 15 digits).
`Status é obrigatório`	(Webhook) The payload is missing the status field.
`ID do depósito é obrigatório`	(Webhook) The payload is missing the deposit identifier.

Example Body:

{
  "error": "amountInCents deve ser um inteiro positivo"
}

`401 Unauthorized`

Authentication failed due to missing or invalid credentials.

Error Message	Description
`Credenciais do gateway ausentes`	Missing API Key, Timestamp, or Signature headers.
`Timestamp fora da janela permitida`	Request timestamp is older than 5 minutes or in the future.
`Assinatura inválida`	The HMAC signature does not match the request content.
`Secret inválido`	(Webhook) The webhook signature provided does not match the stored secret.

Example Body:

{
  "error": "Assinatura inválida"
}

`403 Forbidden`

The client is authenticated but does not have permission to access the resource.

Error Message	Description
`IP não autorizado`	The request came from an IP address not listed in the client's allowlist.
`API Key is not active`	The provided API key has been suspended or revoked.

Example Body:

{
  "error": "IP não autorizado"
}

`404 Not Found`

The requested resource does not exist.

Error Message	Description
`Depósito não localizado`	The provided deposit ID does not exist or belongs to another client.
`Usuário não encontrado`	The requested EUID does not exist in the system.

Example Body:

{
  "error": "Depósito não localizado"
}

`409 Conflict`

The request conflicts with the current state of the resource.

Error Message	Description
`Requisição em processamento`	The provided `X-Idempotency-Key` is currently being processed. Please wait.

Example Body:

{
  "error": "Requisição em processamento. Aguarde alguns instantes."
}

`422 Unprocessable Entity`

The request is well-formed but violates business rules.

Error Message	Description
`Limite diário excedido`	The user (EUID) has reached their daily transaction limit.

Example Body:

{
  "error": "Limite diário excedido"
}

`429 Too Many Requests`

The client has exceeded the rate limit.

Error Message	Description
`Limite de requisições excedido`	You have sent too many requests in a short period.

Response Headers:

Retry-After: Seconds to wait before retrying.

Example Body:

{
  "error": "Limite de requisições excedido",
  "retryAfter": 30
}

💥 Server Errors (5xx)

These errors indicate a problem on the FlamPix side.

`500 Internal Server Error`

An unexpected error occurred on the server.

Error Message	Description
`Erro interno ao consultar depósito`	A database or system error prevented the lookup.
`Split address não configurado`	Critical configuration error on the gateway server.
`Erro interno no processamento do webhook`	The server failed to process the incoming webhook.

Example Body:

{
  "error": "Erro interno ao consultar depósito"
}

`502 Bad Gateway`

The gateway received an invalid response from an upstream server (e.g., Eullen/DePix API).

`503 Service Unavailable`

The service is temporarily unavailable, usually due to maintenance or high load.

`504 Gateway Timeout`

The upstream server failed to respond in time.

API Responses

✅ Success Responses (2xx)#

200 OK#

❌ Client Errors (4xx)#

400 Bad Request#

401 Unauthorized#

403 Forbidden#

404 Not Found#

409 Conflict#

422 Unprocessable Entity#

429 Too Many Requests#

💥 Server Errors (5xx)#

500 Internal Server Error#

502 Bad Gateway#

503 Service Unavailable#

504 Gateway Timeout#

✅ Success Responses (2xx)

`200 OK`

❌ Client Errors (4xx)

`400 Bad Request`

`401 Unauthorized`

`403 Forbidden`

`404 Not Found`

`409 Conflict`

`422 Unprocessable Entity`

`429 Too Many Requests`

💥 Server Errors (5xx)

`500 Internal Server Error`

`502 Bad Gateway`

`503 Service Unavailable`

`504 Gateway Timeout`