Errors

In this guide, we will talk about what happens when something goes wrong while you work with the API. We use the RFC 9457 Problem Details standard for consistent, machine-readable error responses.

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the problem details to figure out what has gone wrong and do some rudimentary debugging (before contacting support).

RFC 9457 Problem Details

All error responses follow the RFC 9457 Problem Details standard. This provides a consistent, machine-readable format for conveying error information across all API endpoints.

Error responses use the application/json media type.

Standard Fields

  • Name
    type
    Type
    string
    Description

    A URI identifying the problem type. Defaults to about:blank when the problem has no additional semantics beyond the HTTP status code.

  • Name
    title
    Type
    string
    Description

    A short, human-readable summary of the problem. This should not change between occurrences.

  • Name
    status
    Type
    integer
    Description

    The HTTP status code for this occurrence of the problem.

  • Name
    detail
    Type
    string
    Description

    A human-readable explanation specific to this occurrence of the problem.

  • Name
    instance
    Type
    string
    Description

    A URI reference that identifies this specific occurrence of the problem.

Status codes

Here is a list of the different categories of status codes returned by the Stacc Mortgage API.

  • Name
    2xx
    Description

    A 2xx status code indicates a successful response.

  • Name
    4xx
    Description

    A 4xx status code indicates a client error — this means it's a you problem.

  • Name
    5xx
    Description

    A 5xx status code indicates a server error — you won't be seeing these.

Error Examples

Basic Error

A standard error response with the core Problem Details fields.

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "The party with ID '12345' was not found.",
  "instance": "/party/12345"
}

Validation Error

When request validation fails, the response includes an errors array with details about each validation failure.

  • Name
    errors
    Type
    array
    Description

    List of validation errors, each containing:

    • name: The field that failed validation
    • reason: Description of the validation failure
{
  "type": "https://example.net/validation-error",
  "title": "Validation Failed",
  "status": 400,
  "detail": "The request contains invalid fields.",
  "errors": [
    {
      "name": "nin",
      "reason": "National identity number must be 12 digits"
    },
    {
      "name": "email",
      "reason": "Invalid email format"
    }
  ]
}

Server Error

Internal server errors provide minimal detail to avoid exposing sensitive information.

{
  "type": "about:blank",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred. Please try again later.",
  "instance": "/party"
}

Handling Errors

When handling errors from the API:

  1. Check the status code to determine the error category
  2. Read the title for a quick summary of what went wrong
  3. Use the detail for specific information about this occurrence
  4. For validation errors, iterate through the errors array to display field-specific messages to users
try {
  const response = await fetch("/api/party", {
    method: "POST",
    body: JSON.stringify(data),
  });

  if (!response.ok) {
    const problem = await response.json();

    if (problem.errors) {
      // Handle validation errors
      problem.errors.forEach((error) => {
        console.error(`${error.name}: ${error.reason}`);
      });
    } else {
      // Handle other errors
      console.error(`${problem.title}: ${problem.detail}`);
    }
  }
} catch (error) {
  // Handle network errors
}