Response Codes

📘

Understanding API Responses

This guide explains all HTTP status codes returned by LendFoundry APIs, including success codes, client errors, and server errors. Understanding these codes helps you handle API responses effectively and troubleshoot issues.

LendFoundry APIs use standard HTTP status codes to indicate the result of API requests. This document provides a comprehensive reference for all status codes you may encounter, along with example responses and troubleshooting guidance.

Overview

LendFoundry APIs return standard HTTP status codes following REST API conventions. Each response includes:

• HTTP Status Code - Numeric code indicating request outcome
• Status Text - Human-readable status description
• Response Body - JSON payload with data or error details

Response Categories

Success Codes

Success codes indicate that the request was processed successfully. The response body contains the requested data or confirmation.

200 OK

The request succeeded. The response body contains the requested resource data.

Common Use Cases:

• Retrieving a resource (GET requests)
• Successful update operations (PUT/PATCH requests)
• Successful query operations

Example Response:

{
  "loanNumber": "LN-2024-001",
  "status": "Active",
  "borrowerName": "John Doe",
  "principalBalance": 50000.00,
  "nextPaymentDate": "2024-02-15",
  "nextPaymentAmount": 1250.00
}

201 Created

The resource was created successfully. The response body contains the newly created resource with its assigned identifier.

Common Use Cases:

• Creating a new application (POST to /applications)
• Creating a new loan (POST to /loans)
• Creating a new payment (POST to /payments)

Example Response:

{
  "applicationNumber": "APP-2024-001",
  "status": "Submitted",
  "createdAt": "2024-01-15T10:30:00Z",
  "borrowerName": "Jane Smith",
  "requestedAmount": 100000.00
}

204 No Content

The request succeeded, but there is no content to return. The response body is empty.

Common Use Cases:

• Successful DELETE operations
• Successful update operations that don't return data

Example Response:

(Empty response body)

Client Error Codes

Client error codes indicate that the request was invalid or cannot be processed due to client-side issues. These errors require fixing the request before retrying.

400 Bad Request

The request is malformed or contains invalid data. The server cannot process the request due to client error.

Common Causes:

• Missing required fields
• Invalid data types
• Malformed JSON
• Invalid parameter values
• Business rule violations

Example Response:

{
  "error": "Bad Request",
  "message": "Invalid request payload",
  "details": [
    {
      "field": "loanAmount",
      "message": "loanAmount must be a positive number"
    },
    {
      "field": "term",
      "message": "term is required"
    }
  ],
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/v1/loan-management/loans"
}

Troubleshooting:

• Verify all required fields are included
• Check data types match the API specification
• Validate JSON syntax
• Review field constraints and business rules

401 Unauthorized

Authentication failed. The request lacks valid authentication credentials or the token is invalid or expired.

Common Causes:

• Missing Authorization header
• Invalid or expired token
• Token format incorrect (missing Bearer prefix)
• Token revoked or deactivated

Example Response:

{
  "error": "Unauthorized",
  "message": "Invalid or expired authentication token",
  "timestamp": "2024-01-15T10:30:00Z"
}

Troubleshooting:

• Verify the Authorization header is included
• Ensure token is prefixed with Bearer (with a space)
• Check token expiration and refresh if needed
• Confirm you're using the correct token for the environment

📘

Note

See the Authentication Guide for detailed authentication instructions.

403 Forbidden

Access denied. The request is authenticated but lacks sufficient permissions to access the resource.

Common Causes:

• Token lacks required permissions
• Attempting to access resources outside tenant scope
• Resource access restricted by policy

Example Response:

{
  "error": "Forbidden",
  "message": "Insufficient permissions to access this resource",
  "timestamp": "2024-01-15T10:30:00Z"
}

Troubleshooting:

• Verify token has required permissions
• Check that you're accessing resources within your tenant scope
• Contact your administrator to review token permissions

404 Not Found

The requested resource does not exist or cannot be found.

Common Causes:

• Invalid resource identifier (ID, number, etc.)
• Resource was deleted
• Incorrect endpoint URL
• Resource belongs to different tenant

Example Response:

{
  "error": "Not Found",
  "message": "Loan with number 'LN-9999-999999' not found",
  "timestamp": "2024-01-15T10:30:00Z"
}

Troubleshooting:

• Verify the resource identifier is correct
• Check the endpoint URL matches the API specification
• Confirm the resource exists and hasn't been deleted
• Ensure you're querying the correct tenant/environment

409 Conflict

The request conflicts with the current state of the resource.

Common Causes:

• Duplicate resource creation
• State conflict (e.g., onboarding already onboarded application)
• Concurrent modification conflict
• Resource already exists with same identifier

Example Response:

{
  "error": "Conflict",
  "message": "Application has already been onboarded",
  "existingLoanNumber": "LN-2024-001",
  "timestamp": "2024-01-15T10:30:00Z"
}

Troubleshooting:

• Check if the resource already exists
• Verify the current state of the resource
• Review business rules for state transitions
• Use GET request to check current state before modifying

422 Unprocessable Entity

The request is well-formed but cannot be processed due to semantic errors or validation failures.

Common Causes:

• Validation rule violations
• Business rule violations
• Invalid state transitions
• Data format valid but semantically incorrect

Example Response:

{
  "error": "Unprocessable Entity",
  "message": "Validation failed",
  "details": [
    {
      "field": "paymentAmount",
      "message": "Payment amount exceeds outstanding balance"
    },
    {
      "field": "paymentDate",
      "message": "Payment date cannot be in the past"
    }
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

Troubleshooting:

• Review validation error details in the response
• Check business rules and constraints
• Verify data values meet requirements
• Review API documentation for field requirements

429 Too Many Requests

Rate limit exceeded. Too many requests were sent in a given time period.

Common Causes:

• Exceeding API rate limits
• Too many concurrent requests
• Rapid successive requests

Example Response:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after some time",
  "retryAfter": 60,
  "timestamp": "2024-01-15T10:30:00Z"
}

Troubleshooting:

• Wait for the specified retry period (retryAfter seconds)
• Implement exponential backoff in your client
• Reduce request frequency
• Contact support if limits need adjustment

Server Error Codes

Server error codes indicate that the server encountered an error while processing the request. These errors may be retryable.

500 Internal Server Error

An unexpected server error occurred. The request may succeed if retried.

Common Causes:

• Server-side processing error
• Database connection issues
• Unexpected exception
• System overload

Example Response:

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred. Please try again later.",
  "referenceId": "ERR-2024-ABC123",
  "timestamp": "2024-01-15T10:30:00Z"
}

Troubleshooting:

• Retry the request after a short delay
• If the error persists, note the referenceId and contact support
• Check system status for known issues
• Implement retry logic with exponential backoff

502 Bad Gateway

The server received an invalid response from an upstream server.

Common Causes:

• Upstream service unavailable
• Gateway timeout
• Network issues between services

Example Response:

{
  "error": "Bad Gateway",
  "message": "Invalid response from upstream server",
  "timestamp": "2024-01-15T10:30:00Z"
}

Troubleshooting:

• Retry the request after a short delay
• Check system status for service outages
• Contact support if the issue persists

503 Service Unavailable

The service is temporarily unavailable, often due to maintenance or overload.

Common Causes:

• Scheduled maintenance
• Service overload
• Temporary unavailability

Example Response:

{
  "error": "Service Unavailable",
  "message": "The service is temporarily unavailable. Please try again later.",
  "retryAfter": 300,
  "timestamp": "2024-01-15T10:30:00Z"
}

Troubleshooting:

• Wait for the specified retry period
• Check system status page for maintenance windows
• Implement retry logic with appropriate delays
• Contact support if unavailability persists

504 Gateway Timeout

The server did not receive a timely response from an upstream server.

Common Causes:

• Upstream service timeout
• Slow database queries
• Network latency issues

Example Response:

{
  "error": "Gateway Timeout",
  "message": "The server did not respond in time",
  "timestamp": "2024-01-15T10:30:00Z"
}

Troubleshooting:

• Retry the request
• Check if the request is processing a large dataset
• Consider breaking large requests into smaller batches
• Contact support if timeouts persist

Error Response Format

All error responses follow a consistent structure to make error handling predictable and straightforward.

Standard Error Structure

{
  "error": "Error Type",
  "message": "Human-readable error message",
  "details": [
    {
      "field": "fieldName",
      "message": "Specific error message for this field"
    }
  ],
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/v1/endpoint/path"
}

Error Response Fields

Field-Specific Error Details

For validation errors (400, 422), the details array contains field-specific errors:

{
  "details": [
    {
      "field": "loanAmount",
      "message": "loanAmount must be a positive number"
    },
    {
      "field": "term",
      "message": "term is required"
    }
  ]
}

Error Handling Best Practices

1. Check Status Code First

Always check the HTTP status code before processing the response body:

const response = await fetch(url, options);
if (!response.ok) {
  // Handle error based on status code
  const error = await response.json();
  // Process error
}
const data = await response.json();

2. Handle Retryable Errors

Implement retry logic for server errors (500, 502, 503, 504) and rate limits (429):

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.ok) {
        return await response.json();
      }
      
      // Check if retryable
      if ([500, 502, 503, 504, 429].includes(response.status)) {
        const error = await response.json();
        const delay = error.retryAfter || Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      
      // Non-retryable error
      throw new Error(`HTTP ${response.status}`);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
}

3. Parse Error Details

Extract and display field-specific errors for better user experience:

if (response.status === 400 || response.status === 422) {
  const error = await response.json();
  error.details?.forEach(detail => {
    console.error(`Field ${detail.field}: ${detail.message}`);
  });
}

4. Log Error Reference IDs

For server errors, log the reference ID for support:

if (response.status === 500) {
  const error = await response.json();
  console.error(`Server error. Reference ID: ${error.referenceId}`);
  // Include referenceId when contacting support
}

Quick Reference Table

Next Steps

Now that you understand response codes, explore these resources:

✅

Ready to Handle Errors Effectively?

Head to the Error Handling Guide to learn advanced error handling strategies and best practices.