Error Handling
This section describes the full set of response codes returned by the Prefill APIs, with guidance on how to handle each scenario.
200 — Success (No Warnings)
The payload was accepted and the prefill record was created. Redirect the customer to the returned URL.
200 — Success with Warnings
The payload was accepted and the journey will launch, but one or more fields were flagged. The warnings array will contain details. Redirect the customer as normal and log warnings for remediation. Warnings are non-blocking — do not alert the customer.
400 — Bad Request (Validation Failure)
A required field is missing, malformed, or uses an invalid value. The prefill record was NOT created. Do not redirect the customer. Inspect the warnings array to identify which field caused the failure. Fix the payload and resubmit with a new Idempotency-Key. Do not retry a 400 with the same payload.
401 — Unauthorized
The access token is missing, malformed, or expired. Common causes: no Authorization header included; Bearer token has expired (tokens are valid for 1 hour), or token is malformed or issued for a different environment.
Action: Request a new token via the Token API and retry the request.
403 — Forbidden
The partner is authenticated but not authorized for this action. Common causes: credentials do not have permission for this endpoint, or a recordId is being accessed by a partner whose producerCode does not match the record’s owner.
Action: Do not retry. Contact your Co‑operators integration contact to verify your partner configuration.
404 — Not Found
The requested endpoint or route does not exist. Verify the base URL and path.
409 — Conflict (Idempotency Violation)
A request was submitted with an Idempotency-Key that was already used for a different payload. The request is rejected to prevent ambiguity.
Action: Generate a new Idempotency-Key (UUID) for each logically distinct submission.
429 — Too Many Requests
Your integration has exceeded the rate limit for the endpoint. Response headers will include:
Action: Pause requests for at least the number of seconds indicated in Retry-After. Implement client-side rate limiting and exponential backoff.
5xx — Server Errors
Unexpected server-side failures. These are transient in most cases.
-
500 = Internal server error.
-
502 = Bad gateway (upstream dependency failure).
-
503 = Service temporarily unavailable.
Action: Safe to retry if using Idempotency-Key correctly. Apply exponential backoff with a maximum retry count. If the issue persists beyond a few minutes, contact Co‑operators support.