Error Handling

Technical error vs. negative outcome

The handling described here refers to technical errors — where the system cannot process a request it has received. For example, if the request did not conform to the schema specified for that operation.

This is distinct from a negative outcome, which can result from a request that has been successfully received and processed. An example of a negative outcome would be that an incoming payment can't be received because the beneficiary's account has been closed.

The Electrum API communicates errors using a combination of an HTTP status code and a message payload. The HTTP status defines the general class of error and, if possible, the specific technical condition experienced by the system. The message payload provides further detail about the error in a human-readable format.

If an error occurs while processing a request from Electrum, then you must respond with one of the supported HTTP statuses and a valid message payload. Include a concise description of the error in the message field of the payload, and optionally a more detailed description in the detail field.

If Electrum encounters an error while processing a request from you, Electrum will respond with one of the supported HTTP statuses and a valid message payload. The HTTP status will guide you as to the required course of action, while the contents of the payload will assist with further troubleshooting.

HTTP Status Codes

The API provides for HTTP errors that fall into the 4xx and 5xx categories. These categories group errors broadly into those originating on the client side and those on the server side, respectively. An error in the 4xx class usually means the message cannot be processed because it is malformed in some way. The data in the message would need to be corrected before the request can be tried again. An error in the 5xx class is related to a technical issue experienced by the server that prevents it from processing the request. Such an issue is often temporary and the exact same request could be retried at a later time.

The API reference pages specify the exact status codes supported for each operation.

Error Message Payload

The error message payload is intended to provide additional, human-friendly information about the issue. The message is defined by the following schema:

Bad request. RFC9110 - 400

Response Schema: application/json

detail	string An optional string containing details relevant to the error, for example an explanation of which field(s) in a message body failed validation and why.
message required	string A human friendly description of the error that occurred.
schema required	string Value: "ErrorDetail"

application/json

{"detail": "string",
"message": "string",
"schema": "ErrorDetail"
}