Web Function

Introduction

Errors are an inevitable part of any API interaction. This specification standardizes the error format such that error handling can be automated and improved across different clients and services. This specification also introduces a flag for endpoint definition in Web Function Package to indicate the use of this specification.

Error response format

The error response for a Web Function Endpoint MUST use the following array structure when the HTTP status code is 400:

[
  ERROR_CODE,
  ERROR_MESSAGE,
  ERROR_DETAILS
]

Key and type	Description
ERROR_CODE string	A short, machine-readable code representing the specific error condition encountered.
ERROR_MESSAGE string	A human-readable explanation of the error, intended to provide more context and assist in resolution.
ERROR_DETAILS any	Any JSON value with additional details about the error. The structure of this value may vary based on the error but should provide enough data to diagnose and address the issue.

Package endpoint flag

Endpoints that conform to this error specification and are part of Web Function Package definition SHOULD include the error_triple flag. This flag signifies that the endpoint adheres to the specified error response structure and should be treated accordingly by clients.

It's worth noting that it is not recommended to add "array" to the list of possible return types if this flag is used. Rather, clients implementing this spec MUST handle this case automatically.

Listing errors in packages and endpoints

When using the error_triple flag, both packages and endpoints MAY declare the set of possible error codes they return.

PACKAGE_ERRORS provides a shared list of ERROR_CODEs applicable across multiple endpoints within the package. Use this for errors that are not endpoint-specific, such as auth failures, rate limits, or system issues.
ENDPOINT_ERRORS declares the ERROR_CODEs specific to a given endpoint, often tied to business logic or input validation.

Clients SHOULD refer to these lists only when the error_triple flag is enabled.

Example error response

A typical error response from an endpoint using error_triple might look like this:

[
  "INVALID_PAYLOAD",
  "The data provided in the request payload is invalid.",
  [
    {
      "field": "username",
      "error": "Missing required field"
    }
  ]
]

Example package definition

An example endpoint definition in a Web Function Package that uses the flag might look like this:

{
  "base_url": "https://api.example.com",
  "name": "ExamplePackage",
  "flags": [],
  "docs": "This package defines endpoints for Example API.",
  "endpoints": [
    {
      "name": "find-user-by",
      "returns": ["object"],
      "flags": ["error_triple"],
      "docs": "Retrieves user data.",
      "arguments": [
        {
          "name": "id",
          "type": "string",
          "flags": ["required"],
          "docs": "Identifier of the user."
        }
      ]
    }
  ]
}

Validation requirements

Endpoints MUST validate incoming requests against the defined schema. If validation fails, the endpoint MUST return an error response adhering to the format defined in this specification.