Errors

Outlines the default error response schema, and some common error types.

Error

Default response schema for 4xx and 5xx HTTP status codes.

Table

Parameter	Type	Description
status	integer	The HTTP status code
message	string	The error message
errors	array	The errors

Formats

Example

An example error response:

{
  "status": 400,
  "message": "Bad Request",
  "errors": ["Invalid request body"]
}

JSON Schema

The JSON schema for this model is:

$schema: https://json-schema.org/draft/2020-12/schema
$id: Error.yaml
type: object
properties:
  status:
    type: integer
    description: The HTTP status code
  message:
    type: string
    description: Human-readable error message
  errors:
    type: array
    description: List of errors
required:
  - status
  - message
  - errors

TypeSpec

The TypeSpec code for this model is:

/** A standard error response schema, used to create custom error responses
 *
 * @example - How to use this model to create custom error response schemas
 *
 * ```
 * import "@typespec/http"
 *
 * alias Unauthorized = Error & Http.UnauthorizedResponse
 * ```
 */
@error
@doc("A non-2xx response schema")
model Error {
  @example(400)
  status: int32;

  /** Human-readable error message */
  @example("Error")
  message: string;

  /** List of errors */
  errors: Array<unknown>;
}

OpenAPI

The OpenAPI specification for this model is:

paths:
  /foo:
    get:
      responses:
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommonGrants.Responses.Error"

Where the CommonGrants.Responses.Error component is defined as:

components:
  schemas:
    CommonGrants.Responses.Error:
      type: object
      properties:
        status:
          type: integer
          description: The HTTP status code
        message:
          type: string
          description: Human-readable error message
        errors:
          type: array
          description: List of errors
          items:
            type: unknown
      required:
        - status
        - message
        - errors

Usage

Here’s an example of how to use the Error response within an API operation:

import "@common-grants/core";
import "@typespec/http";

using TypeSpec.Http;
using CommonGrants.Responses;

@summary("Get test")
@doc("Get a test model")
@get
op getTest(): Ok<TestModel> | Error;

Common Error Types

The following error types are commonly used:

// 401 Unauthorized
// User is not authorized to access the resource
alias Unauthorized = Error & Http.UnauthorizedResponse;

// 404 Not Found
// The resource was not found
alias NotFound = Error & Http.NotFoundResponse;

// 400 Bad Request
// The request was invalid
alias BadRequest = Error & Http.BadRequestResponse;

// 403 Forbidden
// The action is forbidden
alias Forbidden = Error & Http.ForbiddenResponse;