Error Handling and Failure Responses
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.
Error Handling
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.
Some failures may return message content containing a JSON object adhering to the ErrorDetail schema as described below. Note that this object may not be present in all responses and shall be returned at best effort only.
| Status Code | Name | ErrorDetail | Description |
|---|---|---|---|
400 | Bad request | Yes | This server cannot or will not process the request due to something that is perceived to be a client error. |
401 | Unauthorised | No | The request has not been applied because it lacks valid authentication details for the target resource. |
403 | Forbidden | No | The server understood the request but declines to fulfil it. |
405 | Method not allowed | No | The message received in the request line is known by the origin server but not supported by the target resource. |
422 | Unprocessable content | Yes | The server understands the content type and syntax of the request content but was unable to process the contained instructions. |
429 | Too many requests | No | The server has sent too many requests within in a given time period ('rate-limiting'). |
500 | Internal server error | Yes | The server encountered an unexpected condition that prevented it from fulfilling the request. |
503 | Service unavailable | Yes | The service is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay. |
ErrorDetail Message Payload
The ErrorDetail message payload is intended to provide additional, reader-friendly information about the issue. The message is defined by the following schema:
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.
A human friendly description of the error that occurred.