Package org.springframework.web.bind.annotation

Annotation Interface ResponseStatus

@Target({TYPE,METHOD})
@Retention(RUNTIME)
@Documented
public @interface ResponseStatus

Marks a method or exception class with the status code() and reason() that should be returned.

The status code is applied to the HTTP response when the handler method is invoked, but does not override status information set by other means, such as ResponseEntity or "redirect:".

Warning: when using this annotation on an exception class, or when setting the reason attribute of this annotation, the HttpServletResponse.sendError method will be used.

With HttpServletResponse.sendError, the response is considered complete and should not be written to any further. Furthermore, the Servlet container will typically write an HTML error page therefore making the use of a reason unsuitable for REST APIs. For such cases it is preferable to use a ResponseEntity as a return type and avoid the use of @ResponseStatus altogether.

Note that a controller class may also be annotated with @ResponseStatus which is then inherited by all @RequestMapping and @ExceptionHandler methods in that class and its subclasses unless overridden by a local @ResponseStatus declaration on the method.

Since:

3.0

Author:

Arjen Poutsma, Sam Brannen

See Also:

• ResponseStatusExceptionResolver
• HttpServletResponse.sendError(int, String)

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
HttpStatus	code	The status code to use for the response.
String	reason	The reason to be used for the response.
HttpStatus	value	Alias for code().

Element Details

value

@AliasFor("code")
HttpStatus value

Alias for code().

Default:

INTERNAL_SERVER_ERROR

code

@AliasFor("value")
HttpStatus code

The status code to use for the response.

Default is HttpStatus.INTERNAL_SERVER_ERROR, which should typically be changed to something more appropriate.

Since:

4.2

See Also:

• HttpServletResponse.setStatus(int)
• HttpServletResponse.sendError(int)

Default:

INTERNAL_SERVER_ERROR

reason

String reason

The reason to be used for the response.

Defaults to an empty string which will be ignored. Set the reason to a non-empty value to have it used to send a Servlet container error page. In this case, the return value of the handler method will be ignored.

See Also:

• HttpServletResponse.sendError(int, String)

Default:

""