Errors

{ "error": { "code": "invalid_input" } }

​

Error codes

​

Fix the request (4xx, not charged)

​

Wait and retry (429)

​

Something went wrong on our side (5xx)

​

Validation rules that cause 400

• A field name is misspelled or not supported by that endpoint, such as country on a breach endpoint.
• A field is null. Omit optional fields instead of sending null.
• email is not a plain address. Display names such as "Alice <alice@example.com>" are rejected.
• country is not exactly two letters.
• forceToGenderize: true is combined with ai_mode off or always.
• A batch has 0 or more than 50 items, a duplicate id, an id over 100 characters, or an unknown type.
• A value is empty after trimming, or longer than the endpoint’s maximum.

​

Handling errors in code

async function finowl(path, body) {
  const response = await fetch(`https://api.finowl.co${path}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FINOWL_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(40_000),
  });

  const payload = await response.json();
  if (response.ok) return payload;

  const code = payload?.error?.code ?? `http_${response.status}`;
  const retryAfter = Number(response.headers.get("Retry-After")) || undefined;
  throw Object.assign(new Error(code), { status: response.status, code, retryAfter });
}