Go-Live
Error Handling
Recognize ingestion errors and decide when to correct, retry, or reconcile.
Read the status and response body
Use the HTTP status first, then inspect error, message, and details when present. Response shapes vary by validation layer and endpoint. A non-2xx response is not an ALLOW decision. For inline integrations, keep the payment in the agreed pending or failure state until your source system resolves the outcome.
HTTP response handling
Ingestion responses
- 200: read the returned decision and apply the handling documented in Decisions and Risk Outcomes.
- 400: correct missing headers, malformed JSON, or payload validation errors.
- 401: provide a valid organization API key for the correct environment.
- 403: check source-IP access, organization status, or feature permissions.
- 409: retry only when the message says the same idempotency key is still processing; investigate other conflicts.
- 429: back off. Limits can apply before authentication or per organization.
- 5xx: retry transient failures with the original transaction UUID and idempotency key, then reconcile if the result remains uncertain.
Missing API key
The ingestion authentication middleware returns HTTP 401 when x-api-key is missing.
{
"error": "Unauthorized",
"message": "Missing x-api-key header"
}Validation errors
Missing required request headers or fields can produce the framework response below. Payload validation can instead return error and a details array containing field paths and validation messages. Read both forms.
{
"statusCode": 400,
"code": "FST_ERR_VALIDATION",
"error": "Bad Request",
"message": "headers must have required property 'idempotency-key'"
}Rate limits
The following HTTP 429 example uses an illustrative organization limit of 60 requests per minute. Your configured limit can differ. Do not hardcode that number. Back off and honor Retry-After if present; the ingestion middleware does not currently guarantee that header.
{
"error": "Too Many Requests",
"message": "Organization ingestion rate limit exceeded. Max 60 requests per minute.",
"statusCode": 429
}Safe diagnostics
Log HTTP status, transaction UUID, idempotency key, timestamp, and redacted error details. Do not log credentials, cookies, or raw personal data. For repeated 5xx failures or uncertain transaction outcomes, reconcile with your source system and contact Remllo support.