Error Handling

Actionable failure conditions, covered in detail in their relevant sections, are reported as part of 4xx responses in a JSON response body. One or more errors will be returned in the following format:

{
  "errors": [
    {
      "code": "<error identifier>",
      "message": "<message describing condition>",
      "detail": "<unstructured>"
    }
  ]
}
  • The code field will be a unique identifier, all caps with underscores by convention.

  • The message field will be a human-readable string.

  • The optional detail field may contain arbitrary JSON data providing information the client can use to resolve the issue. While the client can take action on certain error codes, the registry may add new error codes over time. All client implementations should treat unknown error codes as UNKNOWN, allowing future error codes to be added without breaking API compatibility. For the purposes of the specification, error codes will only be added and never removed.

Errors

The error codes encountered via the API are enumerated in the following table:

Code
Message
Description

UNKNOWN

unknown error

Generic error returned when the error does not have an API classification

VALIDATE_FAILED

field validation failed

This error code may be returned if a field validation fails.