Errors

AltFiScore uses standard HTTP status codes to indicate success or failure. Every error response is JSON with a stable structure your code can rely on.

Error response shape

Every non-2xx response from the AltFiScore API has the following shape:

Error response

{
  "error": "invalid_request",
  "message": "Field 'transaction.amount' is required.",
  "request_id": "req_5dF8gH3kL2mN1pQ4"
}

error — a stable machine-readable code (see table below). Safe to switch on in your code.
message — a human-readable explanation. Useful for logs; don't display directly to end users.
request_id — unique identifier for this request. Include it when contacting support.

Use the error code, not the message

The error field is part of the stable API contract. The message field may be reworded for clarity over time. Always switch on error in your code; use message only for logging.

Error codes

The full list of error codes you may encounter:

Status	Error code	Description	Retry?
`400`	`invalid_request`	Request body is malformed or required fields are missing.	No retry
`401`	`invalid_api_key`	API key is missing, malformed, or revoked.	No retry
`403`	`permission_denied`	Your key is valid but lacks permission for this endpoint or product.	No retry
`404`	`not_found`	Resource (decision, consumer, application) does not exist or belongs to a different tenant.	No retry
`409`	`idempotency_conflict`	Same Idempotency-Key used with a different request body.	No retry
`422`	`unprocessable_entity`	Request body is well-formed but fails validation (e.g., invalid currency, amount below product minimum).	No retry
`429`	`rate_limited`	You've exceeded the rate limit. Honor the Retry-After header.	Backoff
`500`	`internal_error`	Something went wrong on AltFiScore's end. Safe to retry with the same Idempotency-Key.	Retry
`502`	`bad_gateway`	An upstream data source (e.g., Plaid) failed. Safe to retry.	Retry
`503`	`service_unavailable`	AltFiScore is briefly unable to process requests. Retry with backoff.	Backoff
`504`	`gateway_timeout`	An upstream data source took too long to respond. Safe to retry with the same Idempotency-Key.	Retry

Retry semantics

Retry — safe to retry immediately. Combine with an idempotency key to avoid duplicate decisions.

Backoff — retry with exponential backoff. Honor the Retry-After header if present.

No retry — the request will fail the same way every time. Inspect the message field, fix the underlying issue, and try again with a new request.

Declines aren't errors

A consumer being declined for a loan is a successful decision, not an error. The API returns HTTP 200 with outcome: "declined" and a populated decline_reasons array.

See the compliance page for guidance on handling adverse action notices.

Rate limits

AltFiScore enforces tenant-level rate limits to protect the platform. Default limits are generous and grow with your plan. If you exceed your limit, you'll receive HTTP 429 with a Retry-After header indicating how long to wait.

If you're hitting limits in production

Contact sales@altfiscore.com to upgrade your plan. We can typically raise limits within a single business day.

Next steps

Build retry-safe integrations with idempotency keys
Handle declines properly via the compliance guide