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	Request completed successfully
400	Invalid Request	Invalid request body or validation error
401	Unauthorized	Missing or invalid API key
404	Not Found	Merchant ID not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error

Common Errors

400 Invalid Request

Invalid merchant_id format:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "merchant_id must be in format M000000"
  }
}

Missing required field:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "loan_amount is required"
  }
}

Invalid format (non-numeric):

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "loan_amount must be a number with up to 2 decimal places"
  }
}

Invalid format (negative number):

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

Loan amount too low:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "loan_amount must be at least £250.00"
  }
}

Loan amount too high:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "loan_amount exceeds maximum limit of £25,000.00"
  }
}

Invalid merchant URL:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "merchant_finance_url is invalid"
  }
}

401 Unauthorized

Missing or invalid API key:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid authorization header. Use: Authorization: Bearer sk_apikey"
  }
}

404 Not Found

Merchant not found:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Merchant M000145 not found"
  }
}

429 Rate Limit Exceeded

Too many requests:

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

Check the rate limit headers in the response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1609459260

500 Internal Server Error

Server-side error:

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}

If you encounter persistent 500 errors, contact partners@finmatch.io.

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 error details