Skip to content

Concept to handle exception

Overview

The framework concept to handle the exception in the API service.

This design to returned a valuable error response with included properties

  • Use the correct status codes

  • Be descriptive

  • Be helpful

  • Provide elaborative information

  • Be empathetic

Framework

Flow

The diagram below described the framework since exception appears and returned standard output

flowchart LR
  %% Component
  source[Source of problems]
  exception[Exception]
  context[Context]
  type[Type]
  error[Error Mapping]
  metadata[Metadata]
  output[Standard Output]

  %% FLow
  source -- raise --> exception -- catch and carry --> context & type --> error
  error -- match --> metadata -- render --> output

Standard reponse for error

The Innotech API (both for internal and public) follows HTTP status code semantics.

2xx codes signify success, 4xx mostly represent user error, 5xx generally correspond to a server error.

The error messages will return a JSON-encoded body that contains error and message fields. Those will provide specific error condition and human-readable message to identify what caused the error.

Standardized response body

For overall when request hit an error, its will returned a jsonable response output following structure:

// The status code is related: 3XX, 4XX, 5XX
{
  "status": "failure",
  "error": {
    // ...Error Detail
    // ...Following metadata attributes
  }
}

The status of the response will returned status='failure' in all failured case.

Then in the body, it will wrap the error in an error object.

The block error contain following fields:

Field Description Required
@type contains a URI identifying the type. Example "types.example.com/standard/id"
trace_id The trace ID for tracing request in multiple system to diagnosis the error X
code A six-character represented the ID of code. Example: ER0001 X
type A detail string code of error in general form X
message A string (in short form) that describes the error with human-readable style X
detail A string (in long form) with detail error with the metadata context related X
timestamp Timestamp in UTC timezone that the error happned in YYYY-MM-DD HH:MM:SS.SSS format X
context The dictionary of context that
request The context boundary for request itself
application The application-specific metadata (version, hashed IPs control,...)
suggestion A suggestion on how to fix the issue. This hint related for client/user perspectifice
documentation_url A URL that reference link into the relevant docs to know more/troubleshoot problems

Example:

// Response status code: 404
{
  "status": "failure",
  "error": {
    "@type": null,
    "trace_id": "a3ebe367-b60b-46b9-95fc-f9550ea99d85",
    "code": "RQ0006",
    "type": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found.",
    "detail": "The path at '/v1/resource' does not exist in the API resrouce",
    "timestamp": "2023-12-08T12:30:45Z",
    "context": {
      "path": "/v1/{endpoint}"
    },
    "request": {
      "host": "127.0.0.1",
      "method": "GET",
      "url": "/{endpoint}",
      "headers": {
        "X-Requested-By": "username"
      },
      "query": {}
    },
    "application": {
      "version": "1.2.3",
      "revision": "20240508"
    },
    "suggestion": "Please check the path of your request",
    "documentation_url": "https://api.example.com/docs/errors"
  }
}

HTTP status code

HTTP Return
HTTP 200 Success code; Request completed successfully.
HTTP 4XX Malformed requests; the issue is on the sender's side.
HTTP 403 return code is used when the WAF Limit (Web Application Firewall) has been violated.
HTTP 409 return code is used when a cancelReplace order partially succeeds.
HTTP 429 return code is used when breaking a request rate limit.
HTTP 418 return code is used when an IP has been auto-banned for continuing to send requests after receiving 429 codes.
HTTP 5XX Internal errors; the issue is on Innotech's side.

TODO

Source Reference