Error Handling

Understanding and handling API errors gracefully.

The FinMatch Partner API uses standard HTTP status codes to indicate the outcome of requests. Errors return a consistent JSON format for easy parsing and debugging. Always check the success field and handle the error object appropriately in your code.

Error Response Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable explanation of what went wrong"
  }
}

HTTP Status Codes

Code	Meaning	Common causes
200	Success	The request succeeded. data.products can still be empty; see No products is not an error
400	Invalid request	The request body failed validation, or isn't valid JSON
401	Unauthenticated	Missing, invalid or inactive API key
404	Not found	The merchant_id doesn't exist, or the endpoint path is wrong
422	Amount out of range	loan_amount is outside the range any credit product can offer
429	Too many requests	More than 100 requests per minute from one API key
500	Server error	A problem on our side, or a merchant whose set-up isn't complete

Branch on error.code, not on message. Codes are stable. Messages are written for people and may be reworded.

Some errors also include a details object with the values involved, for example minimum_required on AMOUNT_TOO_LOW.

Request IDs

Every response has an X-Request-Id header. If you send your own X-Request-Id (or X-Correlation-Id) with the request, we use it and echo it back. Otherwise we generate one, such as rq_f3643a33-369a-4714-9fa6-2209f2643b33. Log it with any error; it's the quickest way for us to find your request.

Common Errors

400 Invalid Request

Invalid merchant_id format:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "merchant_id must be format M123456 or FM-XXXX-XXXX-XXXX"
  }
}

Invalid partner_id format:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "partner_id must be format P123456"
  }
}

partner_id doesn't match your API key:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "partner_id does not match your API key"
  }
}

Missing required field, shown here for loan_amount. The same applies to merchant_id, partner_id and merchant_finance_url:

{
  "success": false,
  "error": {
    "code": "MISSING_FIELD",
    "message": "Required field 'loan_amount' is missing"
  }
}

Too many decimal places, for example "9000.123". Amounts can have up to two decimal places:

{
  "success": false,
  "error": {
    "code": "INVALID_AMOUNT_FORMAT",
    "message": "loan_amount and customer_deposit must have at most 2 decimal places"
  }
}

Not a positive number, for example "0.00", or "9,000.00" with a comma. Don't include commas or a currency symbol:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "loan_amount must be a positive number"
  }
}

Negative deposit:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "customer_deposit must be a non-negative number"
  }
}

Invalid merchant_finance_url:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "merchant_finance_url must be a valid URL"
  }
}

Request body isn't valid JSON:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request must be valid JSON"
  }
}

401 Unauthenticated

Missing header, or a scheme other than Bearer:

{
  "success": false,
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Missing or invalid authorization header. Use: Authorization: Bearer <api_key>"
  }
}

Unknown, revoked or inactive API key:

{
  "success": false,
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Invalid or inactive API key"
  }
}

404 Not Found

Merchant not found:

{
  "success": false,
  "error": {
    "code": "MERCHANT_NOT_FOUND",
    "message": "Merchant M999999 does not exist"
  }
}

Wrong endpoint path, for example a typo such as /v1/finance-quotes:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Endpoint POST /v1/finance-quotes not found"
  }
}

422 Amount Out of Range

These limits are the lowest and highest amounts any credit product can offer, not the merchant's own range. An amount inside these limits but outside what the merchant's products cover returns 200 with no products (see below).

Below the minimum:

{
  "success": false,
  "error": {
    "code": "AMOUNT_TOO_LOW",
    "message": "Loan amount £0.01 is below the minimum £10.00 required for all active products",
    "details": {
      "provided_loan_amount": 0.01,
      "minimum_required": 10
    }
  }
}

Above the maximum:

{
  "success": false,
  "error": {
    "code": "AMOUNT_TOO_HIGH",
    "message": "Loan amount £10000000.00 exceeds the maximum £2000000.00 allowed",
    "details": {
      "provided_loan_amount": 10000000,
      "maximum_allowed": 2000000
    }
  }
}

No products is not an error

When the request is valid but none of the merchant's credit products fits, for example the amount is below or above what their products allow, the API returns 200 with "success": true, "display": false, an empty products array, and a deposit_adjustment if the deposit was raised to meet a minimum. Don't show finance in that case. Some merchants also always return an empty products array; see Non-regulated merchants.

{
  "success": true,
  "data": {
    "summary": { "display": false, "finance_offer_summary": "" },
    "products": []
  }
}

429 Too Many Requests

Rate limit exceeded, when there are more than 100 requests per minute from one API key:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded — maximum 100 requests per minute"
  }
}

Every response carries these rate-limit headers:

RateLimit-Policy: 100;w=60
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 42

RateLimit-Reset is the number of seconds until the window resets. It is not a timestamp. Wait at least that long before retrying.

500 Server Error

Something went wrong on our side:

{
  "success": false,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Something went wrong on our side — please try again later"
  }
}

The merchant's set-up isn't complete. FinMatch needs to finish configuring this merchant, and retrying won't help until we do:

{
  "success": false,
  "error": {
    "code": "MERCHANT_CONFIGURATION_INCOMPLETE",
    "message": "Merchant M000106 is missing required configuration.",
    "details": {
      "merchant_id": "M000106",
      "missing_fields": ["finance_offer_summary"]
    }
  }
}

If you get either of these repeatedly, contact partners@finmatch.io with the X-Request-Id and the merchant_id.

Need Help?

If you're experiencing persistent errors:

1. Check the API Reference for correct request format
2. Verify your partner_id and API key
3. Contact partners@finmatch.io with the error.code, the X-Request-Id and the time of the request