Check the HTTP status and content type before parsing a response. Responses vary by endpoint: an object, an array, a JSON scalar, or no body may be valid.
Handle errors without assuming one body shape
Controller validation failures and controller 400 results are normalized into a ProblemDetails object. Read status, title, detail, instance, traceId, correlationId, errorCode and the errors array. Each errors entry contains field, message and code. This errors array is not the field-to-messages dictionary used by some other APIs.
{
"status": 400,
"title": "Request validation failed",
"detail": "The request contains invalid data.",
"instance": "/api/Application/create-customer",
"traceId": "EXAMPLE_TRACE_ID",
"correlationId": "EXAMPLE_CORRELATION_ID",
"errorCode": "EXAMPLE_ERROR_CODE",
"errors": [
{ "field": "Email", "message": "Supply a valid email address.", "code": "EXAMPLE_FIELD_CODE" }
]
}This illustrates the response shape; example codes are placeholders, not a list of supported values. Use the returned correlation ID when requesting support. Failures from authentication proxies, middleware or the host may have a different body or no body, so retain defensive parsing outside normalized controller validation.
| Result | What to do |
|---|---|
| 400 | Check required fields, GUIDs, query parameters, validation rules and application/offer state. Some current handlers also use 400 for failed business operations. |
| 401 | Verify the token, its expiry and the target environment; complete sign-in again if needed. |
| 403 | Check that the account is permitted to perform the operation. Signing in repeatedly will not grant access. |
| 404 | Check the method, path and identifier. Do not assume every missing record returns 404; some legacy reads return 400. |
| 413 | Reduce the request size; base64 uploads are larger than their original files. |
| 429 | Respect a returned Retry-After header, if present, and reduce request frequency. |
| 5xx or network failure | Treat the result as uncertain. Check whether an operation took effect before retrying a mutation. |
These are client-handling cases, not a claim that every endpoint declares every status. Display useful messages while keeping tokens, passwords, full payloads and customer data out of diagnostic logs. Preserve a request/correlation ID when the server supplies one.
Paginate list endpoints
Use skip as the number of records to skip and take as the page size. Loan and communication lists cap take at 200. Partner-application and invoice-customer routes do not apply that cap in this API. For predictable requests, explicitly choose a positive page size up to 200 rather than relying on a large default. Increase skip by the number of items received. Stop on an empty page, or when an envelope's totalCount has been reached.
GET /api/Loan/get-transactions-paged/{loanId}?skip=0&take=100&descending=true
Authorization: Bearer <token>get-transactions-paged and get-withdrawals return envelopes with data and totalCount. Invoice-customer lookup also returns one such envelope, although Swagger incorrectly declares an array of envelopes; it currently returns 400 when no results are available. Other lists, such as messages and partner applications, return arrays directly. The descending option is available on those two paged loan routes. Check each endpoint's parameters before adding pagination: partner reporting routes, for example, may accept dates instead of skip and take.
Records can change while pages are being read. Reconcile by stable record identifiers where available; offset pagination is not a snapshot guarantee.
Retry according to the operation
Use bounded backoff for retryable reads. The API does not publish one universal request-rate limit, retry schedule or idempotency-key contract.
Some GET routes change state, including application processing and application/customer updates. Treat them as commands: do not prefetch, cache or retry them as ordinary reads. Creation, signing, notification, webhook simulation and withdrawal operations can also have side effects.
For an uncertain result, read the relevant record or contact integration support before repeating the operation. Webhook simulation requests delivery; a successful simulation call does not prove that your receiver accepted the event.