Errors

Failures are modeled too. An error is an ordinary structure marked with the @error trait — its value is exactly "client" (the caller’s fault, ~4xx) or "server" (the service’s fault, ~5xx):

@error("client")
structure NoSuchCity {
    @required
    message: String
}

The @error trait is what makes it an error — message is just a widely-followed convention many generators surface as the exception message.

HTTP status codes

For HTTP protocols, @httpError(code) sets the response status:

@error("client")
@httpError(404)
structure NoSuchCity {
    @required
    message: String
}

@error("server")
@httpError(503)
structure Throttled {
    @required
    message: String
}

Attaching errors to operations

List error shapes in an operation’s errors:

@readonly
operation GetCity {
    input := {
        @required
        cityId: String
    }

    output := {
        @required
        name: String
    }

    errors: [
        NoSuchCity
        Throttled
    ]
}

Only @error-marked structures may appear in an errors list.

Your turn