Errors & unavailable rates

A request error means the API cannot process your input or credentials. An unavailable rate means the request was understood, but no supported amount can be returned for that combination.

Rate validation and location errors use an error object with code, message, and param. Authentication, plan, and throttle errors use the shared API framework’s JSON message field.

• 422: Check the input. Missing setting, invalid dates, and conflicting location parameters must be corrected before retrying.
• 401: Supply a valid bearer token. Check whether the key was revoked.
• 402: An active API plan is required.
• 404: The requested code or resource was not found.
• 429: Slow down and follow Retry-After when present. A quota exhaustion may require waiting for the reset or changing your plan.
• 5xx: A server-side failure. Retry with bounded exponential backoff.

HTTP 422 uses invalid_parameters, zip_plus4_required, or location_not_found. Unknown codes return HTTP 404 with code_not_found. Validation errors include a details object with messages per field.

A valid lookup may return HTTP 200 with amount: null and an unavailable_reason, contractor_priced, setting_unavailable, unsupported_rule, unsupported_payment_status, data_unavailable, code_not_in_release, or rate_not_in_release. A code known to the catalog but absent from the selected release is unavailable rather than an unknown code.

These outcomes do not mean the service is free, non-covered, or categorically not payable. They mean FeeBase cannot supply that base amount under the requested conditions.

The zip_plus4_required error identifies zip as the field to refine. Send a ZIP+4 or use an explicit locality. Repeating the same five-digit ZIP will not resolve the ambiguity.

New resources use the same error.code, message, and param shape. Validation errors include error.details. Resource errors include code_not_in_release, code_set_not_found, and data_unavailable. Provider-rate outcomes add not_billable and unsupported; batch rates retain code_not_found as an unavailable item. A therapy response with complete: false is a successful evaluation with null totals, not a partial payable amount.

quota_exceeded means the team has enabled Stop at included requests and exhausted its included allowance (or additional billing is not yet ready). The owner can disable the limit or upgrade in Plan & billing; otherwise wait until X-Quota-Reset. With the limit off, additional requests continue at the plan’s per-request price. rate_limited remains a separate per-minute restriction.