Errors

Every error the surface emits, what causes it, and whether retrying can help. Errors are RFC 9457 problem documents.

The envelope

Failures return application/problem+json with a stable machine-readable code. Branch on code, not on the HTTP status: two of the codes below share status 429 and need opposite handling.

Error body
{
  "type": "https://gofunditnow.com/developers/errors/quota-exceeded",
  "title": "quota exceeded",
  "status": 429,
  "code": "QUOTA_EXCEEDED",
  "detail": "Monthly allowance for this organization is exhausted.",
  "request_id": "req_d03eb4e82fea1403d88819d0"
}

Every response, success or failure, also carries a GFIN-Request-Id header. Log it. It is how a specific call is located in our logs, and a support request that quotes one is answerable in minutes rather than days.

Reference

Each error body carries a type URL whose final segment is the code in lowercase with dashes, matching the row anchors on this page: QUOTA_EXCEEDED becomes quota-exceeded, which is #quota-exceeded here. The host in that URL is not serving yet, so treat type as a stable identifier to match on rather than a link to follow, and jump to the anchor on this page instead.

Every error code the API emits
CodeStatusRetry?Cause
VALIDATION_ERROR400Only after fixing the requestA parameter is missing, malformed, or out of range. Unknown parameters are rejected rather than ignored, so a typo surfaces here instead of silently returning unfiltered results.
INVALID_CURSOR400Only after fixing the requestThe cursor value is not one we issued. Pass page.next_cursor back verbatim; cursors are opaque and must not be constructed or decoded.
INVALID_CREDENTIAL401NoUnknown or revoked key, or one that does not match the expected format. Check for copied whitespace and for a key that was rotated out.
INSUFFICIENT_SCOPE403NoThe key is valid but does not carry the scope this operation requires. Permanent for this key: issue a new one with the scope.
RESOURCE_NOT_FOUND404NoNo such resource, or one your credential is not permitted to see. The two are deliberately indistinguishable: a different answer for “exists but withheld” would let anyone enumerate private records by watching status codes.
IDEMPOTENCY_CONFLICT409Depends on which causeTwo different causes share this code. Either the Idempotency-Key was used with a different body, in which case use a fresh key for the genuinely different call; or the first call carrying that key is still running, in which case wait and retry with the same key. Minting a fresh key for the in-flight case defeats the protection and can charge you twice.
DUPLICATE_ENDPOINT409NoA webhook endpoint with this URL already exists for your organization. Two endpoints at one receiver would deliver every matching event twice, so the second registration is refused. Add event types to the existing endpoint, or delete it first.
PAYLOAD_TOO_LARGE413Only after fixing the requestThe request body exceeds the accepted size. Split the work into smaller requests.
RATE_LIMITED429Yes, after backoffToo many requests in the current window, either for this credential (120 per minute) or from this IP before authentication (60 per minute). Transient. Honour Retry-After when it is present.
QUOTA_EXCEEDED429NoThe organization’s allowance for the period is spent. Shares a status with RATE_LIMITED but is the opposite situation: no amount of backoff restores a monthly allowance. Branch on code, never on the status alone.
INTERNAL_ERROR500Yes, after backoffSomething failed on our side. Safe to retry with backoff. Quote the request_id if it persists.
SERVICE_UNAVAILABLE503Yes, after backoffA dependency we need was unreachable. We answer 503 rather than guessing, because a fabricated answer is worse than an honest failure.
UPSTREAM_UNAVAILABLE503Yes, after backoffThe upstream service backing this operation did not respond in budget. Retry with backoff.

Retrying safely

What to retry

Retry 500, 503 and RATE_LIMITED with exponential backoff. Do not retry 400, 401, 403 or QUOTA_EXCEEDED: those describe a condition that repeating the request cannot change, and a client that retries them turns one failure into many. 409 is the exception that needs reading: retry it only when the cause is an in-flight first attempt, and then only with the same key.

Retrying a POST safely

Any retry of a metered POST needs an Idempotency-Key that is generated once and reused across attempts. Without it, a request that succeeded upstream but failed to return is indistinguishable from one that never ran, and retrying charges the work twice. Both SDKs do this for you.

A fresh idempotency key per attempt is worse than none at all: it looks like protection while guaranteeing that every retry is treated as new work.

Nothing here is a score

When we cannot compute something, the field is null and the reason is stated. We do not return a zero, a default, or a placeholder percentage that reads like a real answer. If a response looks like a confident number, it is one.