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

A JSON example of this model.

{
  "status": 404,
  "message": "Not Found",
  "errors": [
    "Resource not found"
  ]
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: Error.yaml
type: object
properties:
  status:
    type: integer
    minimum: -2147483648
    maximum: 2147483647
    examples:
      - 400
  message:
    type: string
    examples:
      - Error
    description: Human-readable error message
  errors:
    type: array
    items: {}
    description: List of errors
required:
  - status
  - message
  - errors
description: A non-2xx response schema

TypeSpec

The TypeSpec code for this model.

@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>;
}

Python

The Python code for this model.

class Error(DefaultResponse):
    """A standard error response schema, used to create custom error responses."""

    status: int = Field(
        default=400,
        description="The HTTP status code",
        examples=[400],
    )
    message: str = Field(
        default="Error",
        description="Human-readable error message",
        examples=["Error"],
    )
    errors: list[Any] = Field(
        ...,
        description="List of 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;

ApplicationSubmissionError

A failure to submit an application due to validation errors.

Table

Property	Type	Required	Description
status	integer	Yes	The HTTP status code
message	string	Yes	The error message
errors	Array<unknown>	Yes	The errors

Formats

Example

A JSON example of this model.

{
  "status": 400,
  "message": "Application submission failed due to validation errors",
  "errors": [
    {
      "field": "formA.name",
      "message": "Name is required"
    }
  ]
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: ApplicationSubmissionError.yaml
type: object
properties:
  status:
    type: number
    const: 400
    examples:
      - 400
required:
  - status
allOf:
  - $ref: Error.yaml
unevaluatedProperties:
  not: {}
examples:
  - status: 400
    message: Application submission failed due to validation errors
    errors:
      - field: formA.name
        message: Name is required
description: A failure to submit an application due to validation errors

TypeSpec

The TypeSpec code for this model.

@example(#{
  status: 400,
  message: "Application submission failed due to validation errors",
  errors: #[#{ field: "formA.name", message: "Name is required" }],
})
@Versioning.added(CommonGrants.Versions.v0_2)
@doc("A failure to submit an application due to validation errors")
model ApplicationSubmissionError extends Error {
  @example(400)
  status: 400;
}

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;