Errors can occur in various places: due to invalid client requests or problems on the backend and network side.
Couper specifies some generic error categories (like configuration, server, backend or access_control) to help you identify the occurring problems faster.
Error messages are only sent to the client as a summary. Detailed information is provided via log message. This way, all information can be viewed without accidentally revealing confidential information.
Access control errors in particular require special handling, e.g. sending a specific response for missing login credentials.
For this purpose every access control definition of basic_auth, jwt, oidc or saml2 can define one or multiple error_handler blocks with one or more defined error type labels listed below.
Required permissions are configured for api or endpoint blocks. So errors caused by insufficient permissions can be handled at API or endpoint levels.
A sequence, a simple request or proxy error can be handled in combination with the expected_status attribute for request
and proxy block definitions and an error_handler block with the related type label.
All errors have a specific type. You can find it in the log field error_type. Furthermore, errors can be associated with a list of less specific types. Your error handlers will be evaluated from the most to the least specific one. Only the first matching error handler is executed.
The following table documents error types that can be handled in the respective access control blocks (basic_auth, jwt, saml, beta_oauth2, oidc):
| Type (and super types) | Description | Default handling |
|---|---|---|
access_control |
Access control related errors | Send error template with status 403. |
basic_auth (access_control) |
All basic_auth related errors, e.g. unknown user or wrong password. |
Send error template with status 401 and WWW-Authenticate: Basic header. |
basic_auth_credentials_missing (basic_auth) |
Client does not provide any credentials. | Send error template with status 401 and WWW-Authenticate: Basic header. |
jwt (access_control) |
All jwt related errors. |
Send error template with status 403. |
jwt_token_missing (jwt) |
No token provided with configured token source. | Send error template with status 401. |
jwt_token_expired (jwt) |
Given token is valid but expired. | Send error template with status 403. |
jwt_token_invalid (jwt) |
The token is syntactically not a JWT, or not sufficient, e.g. because required claims are missing or have unexpected values. | Send error template with status 403. |
saml (or saml2) (access_control) |
All saml related errors |
Send error template with status 403. |
oauth2 (access_control) |
All beta_oauth2/oidc related errors |
Send error template with status 403. |
The following table documents error types that can be handled in api blocks:
| Type (and super types) | Description | Default handling |
|---|---|---|
backend |
All catchable backend related errors | Send error template with status 502. |
backend_openapi_validation (backend) |
Backend request or response is invalid | Send error template with status code 400 for invalid backend request or 502 for invalid backend response. |
backend_timeout (backend) |
A backend request timed out | Send error template with status 504. |
backend_unhealthy (backend) |
A backend is unhealthy and will not send the request | Send error template with status 502. |
access_control |
Access control related errors | Send error template with status 403. |
beta_insufficient_permissions (access_control) |
The permission required for the requested operation is not in the permissions granted to the requester. | Send error template with status 403. |
The following table documents error types that can be handled in endpoint blocks:
| Type (and super types) | Description | Default handling |
|---|---|---|
backend |
All catchable backend related errors | Send error template with status 502. |
backend_openapi_validation (backend) |
Backend request or response is invalid | Send error template with status code 400 for invalid backend request or 502 for invalid backend response. |
backend_timeout (backend) |
A backend request timed out | Send error template with status 504. |
backend_unhealthy (backend) |
A backend is unhealthy and will not send the request | Send error template with status 502. |
access_control |
Access control related errors | Send error template with status 403. |
beta_insufficient_permissions (access_control) |
The permission required for the requested operation is not in the permissions granted to the requester. | Send error template with status 403. |
endpoint |
All catchable endpoint related errors |
Send error template with status 502. |
sequence (endpoint) |
A request or proxy block request has been failed while depending on another one |
Send error template with status 502. |
unexpected_status (endpoint) |
A request or proxy block response status code does not match the to expected_status list |
Send error template with status 502. |