Error

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
]

The array MUST contain exactly three elements, in the order shown: ERROR_CODE, then ERROR_MESSAGE, then ERROR_DETAILS. Servers MUST NOT omit or reorder these elements. For forward compatibility, clients MUST read the triple by position and MUST ignore any additional elements beyond the third.

When a client compares an ERROR_CODE against a known value, the comparison MUST be case-insensitive. This is an exception to the case-sensitive string comparison used elsewhere in Web Function.

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.

When the error_triple flag is set and the response status code is 400, the response body MUST be an array (the error triple). Because the error triple is an array, an endpoint using this flag SHOULD include array in its returns only when its successful (200) response is itself expected to be an array. Clients MUST disambiguate by status code: a 200 response carries the endpoint's declared return value, while a 400 response carries the error triple.

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, using the errors array defined in the package specification.

• The package-level errors array 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.

• The endpoint-level errors array declares the error codes specific to a given endpoint, often tied to business logic or input validation.

These declarations are advisory: they document the error codes a client may encounter, but a server MAY return error codes that are not listed, and clients MUST be prepared to handle unlisted codes. 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.