@api‐error

The @api-error annotation represents an exception that may be returned on a resource action.

Syntax

@api-error:visibility httpCode (\Representation<error code>, vendor:tagName) - description

Requirements

Required?	Needs a visibility	Supports versioning	Supports deprecation
×	✓	✓	×

Breakdown

Tag	Optional	Description
:visibility	✓	Visibility decorator
httpCode	×	The HTTP code that will be returned. Example: 404, 403, etc.
\Representation	×	The fully qualified class name for a representation that will be returned.
error code	✓	An optional error code, if your application supports unique error codes, that this error returns. This can either be a numerical code (ex. (1234)), or a fully qualified static accessor (ex. (\Some\Exception::NOT_ALLOWED).
vendor:tagName	✓	Defined vendor tag. See the @api-vendortag documentation for more information. There is no limit to the amount of vendor tags you can specify on a parameter.
description	✓	A short description describing why, or what, this error is.

Examples

Usage with a vendor tag and description type:

/**
 * ...
 *
 * @api-error:public 404 (\ErrorRepresentation, needs:SomeApplicationFeature) - {user}
 */
public function PATCH()
{
    ...
}

With an error code:

/**
 * ...
 *
 * @api-error:public 403 (\ErrorRepresentation<7701>) If the user isn't
 *     allowed to do something.
 */
public function PATCH()
{
    ...
}

Standard usage:

/**
 * ...
 *
 * @api-error:public 404 (\ErrorRepresentation) - If the user isn't allowed
 *     to do something.
 */
public function PATCH()
{
    ...
}