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.
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.
| Code | Status | Retry? | Cause |
|---|---|---|---|
| VALIDATION_ERROR | 400 | Only after fixing the request | A 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_CURSOR | 400 | Only after fixing the request | The cursor value is not one we issued. Pass page.next_cursor back verbatim; cursors are opaque and must not be constructed or decoded. |
| INVALID_CREDENTIAL | 401 | No | Unknown 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_SCOPE | 403 | No | The 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_FOUND | 404 | No | No 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_CONFLICT | 409 | Depends on which cause | Two 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_ENDPOINT | 409 | No | A 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_LARGE | 413 | Only after fixing the request | The request body exceeds the accepted size. Split the work into smaller requests. |
| RATE_LIMITED | 429 | Yes, after backoff | Too 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_EXCEEDED | 429 | No | The 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_ERROR | 500 | Yes, after backoff | Something failed on our side. Safe to retry with backoff. Quote the request_id if it persists. |
| 503 | Yes, after backoff | A dependency we need was unreachable. We answer 503 rather than guessing, because a fabricated answer is worse than an honest failure. | |
| 503 | Yes, after backoff | The 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.
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.