Error Handling#

The Evolu Integrators API uses conventional HTTP status codes. Error responses carry a detail field describing what went wrong.

{
  "detail": "API_INTEGRATION channel is not enabled for this campaign."
}

{  "detail": "API_INTEGRATION channel is not enabled for this campaign."}

Status codes#

Status	Meaning
`202 Accepted`	The entry was accepted (or already existed for the idempotency key).
`401 Unauthorized`	Missing, malformed, unknown, expired, or deactivated API key.
`403 Forbidden`	The campaign's registration window is closed.
`422 Unprocessable Content`	The request failed validation — see below.

A successful submission is always 202 — even when the entry is ultimately rejected during processing. Rejection is a processing outcome delivered via the entry.completed webhook, not an HTTP error.

422 — validation errors#

A 422 is returned before the entry is created. Common causes:

Payload validation#

A missing required object (enrollment, consent, or evidence).
document_number missing, or not a valid CPF or CNPJ (checksum verified).
full_name shorter than 3 characters.
email that is not a valid address.
phone that does not have 10 or 11 digits.
birthdate that is not a past YYYY-MM-DD date.
address.state that is not a valid Brazilian UF.
consent.granted_at that is not a full ISO 8601 datetime with timezone.
consent.ip_address that is not a valid IPv4/IPv6 address.
evidence.type other than fiscal_key, or an access_key outside 44–50 digits.
A missing Idempotency-Key header.

Campaign configuration#

Channel not enabled — the campaign does not permit the API_INTEGRATION channel.
Evidence not enabled — the campaign does not permit FISCAL_KEY evidence.
CNPJ not allowed — a CNPJ (company) participant was submitted to a campaign whose guard settings do not allow company participants.
Missing required enrollment field — the campaign requires an enrollment field (e.g. phone, city) that is neither in the request nor already stored on the enrollment.

Enrollment uniqueness#

email and phone are unique within a campaign. Submitting a value already used by a different participant is rejected:

{
  "detail": "email is already used by another enrollment in this campaign."
}

{  "detail": "email is already used by another enrollment in this campaign."}

A repeat submission for the same document_number is never rejected for a PII mismatch: fields already stored are kept and any differing values in the new payload are ignored.

Retrying#

401 / 403 / 422 are not retryable — fix the request first.
Transient network errors are safe to retry: reuse the same Idempotency-Key so the retry never duplicates the entry. See Idempotency.