# Error handling

Custom error objects and messages will be returned to the used in case of a unexpected failure. Global error objects could be defined which could be overridden inside flows or resources.

```bash
error "proto.Error" {
	message = "{{ error:message }}"
	status = "{{ error:status }}"
}

flow "GlobalHandleError" {
	input "proto.Empty" {}

	resource "query" {
		request "proto.Service" "ThrowError" {
		}

		on_error {
			status = 401
			message = "global error message"
		}
	}

	output "proto.Empty" {}
}
```

{% hint style="info" %}
Currently is it only possible to return a custom error object through the HTTP protocol. gRPC and GraphQL only support the ability to return a status code and error message.
{% endhint %}

### Expected status code

A list of expected status codes defines which status codes could be expected to be returned from the given service. This prevents a resource from failing even if non OK status codes are returned. Multiple status codes could be expected and result in a pass.

```bash
flow "NotFound" {
	resource "query" {
		request "org.Service" "Prevent" {
			expect_status = [200, 404]
		}
	}
}
```

### Error object

A custom error object could be defined inside a `error` block. This object is used to create a custom error object and headers which is returned to the user. All resources could be referenced inside the error object but no dependencies are created. It is advised to make use of the `error.params` resource to pass custom values such as trace ids, custom status codes etc.

Error objects could be defined as a global object, flow object or resource object. Each layer could override the parent layer. If a global object and flow object are defined is the flow object used for resource definitions.

```bash
error "org.Error" {
	header {
		X-Trace = "{{ error.params:trace }}"
	}

	message "meta" {
		trace = "{{ error.params:trace }}"
	}
		
	message = "{{ error:message }}"
	status = "{{ error:status }}"
}
```

### On Error

A on error block could be defined which defines which status code and message should be returned to the user. Params could be defined with constant values or references to other resource. The `error` and `error.params` resource could be used inside error blocks to access these values. Schema definitions could be included which are used to decode the service error message. Service error message properties could be accessed through the resource.

`on_error` definitions could be overridden by flows and resources. If no `on_error` is defined is the parent definition used.

```bash
on_error {
  schema = "org.Schema"
  status = "{{ error:status }}"
  message = "custom error message"
  
  params {
    trace = "{{ trace:id }}"
    level = "critical"
    reason = "{{ resource.error:reason }}"
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://jexia.gitbook.io/semaphore/cookbook/flows/error-handling.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.