Fincheck

Errors

Read an error response and decide whether to correct, retry, or contact support.

FincheckEngine uses standard HTTP status codes. A 2xx status means the request succeeded, 4xx means something in the request needs to change, and 5xx means something went wrong on Fincheck's side. The status is the error code: response bodies carry a message, not a separate code.

Status codes

StatusWhat it meansSuggested action
400The JSON, form, or file could not be read.Fix the request format. Do not retry unchanged.
401The API key is missing or rejected.Send Authorization: Bearer fce_… with a key for this environment. See Authentication.
403The key cannot access this resource, for example another affiliate's batch.Use the key that created the resource. Do not retry unchanged.
404The lead, intent, or batch does not exist in this environment, or the lead is not yours.Check the id and the environment.
415POST /lead or POST /offer was not sent as application/json.Send Content-Type: application/json.
422The request was read, but a field or business rule failed.Correct the fields named in the response, then send again.
500An unexpected error occurred.Retry with backoff. Contact support if it keeps happening.
503The API is in maintenance, or processing took longer than the request allows.Retry later with backoff. Keep any id you already received.

Error responses

Field validation

JSON
{
  "message": "Validation failed.",
  "errors": {
    "id_number": ["must be a valid RSA ID number"],
    "gross_income": ["must be an integer"]
  }
}

Each key in errors is a JSON field you sent, with one or more messages. Read the keys as they are; they match your request fields exactly.

MessageCause
invalidA name contains digits, unsupported characters, or UnConfirmed.
must be a valid RSA ID numberThe ID number has an invalid date or checksum.
Client must give consent.popi is missing or not true.
required when intent is not presentNeither intent nor intent_id was sent.
must be an integer, must be a number, must be a boolean, must be a string, must be an array of integersThe value has the wrong JSON type, for example "25000" instead of 25000, or "yes" instead of true.
is not supported; use partner_idsThe singular partner_id was sent on POST /lead or POST /offer.
is not supported; use live_quoteslive_score was sent on POST /accept.

Missing intent fields

POST /offer can require extra fields for the chosen intent:

JSON
{
  "message": "intent schema validation failed",
  "missing_fields": ["gross_income", "loan_amount_required"]
}

Add the fields in missing_fields and send the request again. GET /api/v2/intent lists each intent's required fields.

Business rules

JSON
{
  "message": "intent is not accepting leads"
}
MessageSuggested action
intent not foundUse a title or id from GET /intent. Intents differ between environments.
intent is not accepting leadsChoose an active intent from GET /intent.
referee_id not foundCheck the referee_id value, or leave it out.

For accept-specific messages, see Accepting an Offer.

Authentication

JSON
{
  "error": "unauthorized"
}

An expired key returns {"error": "api key expired"} instead. See Authentication for what to check.

Retrying safely

  • Correct 400, 401, 403, 404, and 422 responses before sending again. Retrying them unchanged gives the same result.
  • Retry 500 and 503 with exponential backoff, for example after 1, 2, 4, and 8 seconds, and then stop.
  • Resending a POST /lead for the same applicant is safe: inside the deduplication window it returns the existing lead id.
  • Never repeat POST /accept after a timeout. Check the lead with GET /lead/{hashid} first.
  • For batches, poll the existing batch_id instead of uploading the file again.

Contacting support

Email support@finch-technologies.com with:

  • the environment and endpoint;
  • the HTTP status and response body;
  • the lead id or batch id; and
  • the time of the request.

Never send your full API key or unredacted applicant data.