ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-25 06:05:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Re-level non-docs content to top of repo and rename content→docs

Browse Source
This commit is contained in:
mDuo13
2024-01-31 16:24:01 -08:00
parent f841ef173c
commit c10beb85c2
2907 changed files with 1 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
docs/references/http-websocket-apis/api-conventions/ctid.md Normal file
View File

@@ -0,0 +1,33 @@
---
html: ctid.html
parent: api-conventions.html
seo:
description: A Compact Transaction Identifier (CTID) is a short string that uniquely identifies a validated transaction across any chain.
labels:
- Development
---
# Compact Transaction Identifier
A Compact Transaction Identifier (CTID) is a unique identifier for a validated transaction that applies across any [network](../../../concepts/networks-and-servers/parallel-networks.md), not just the XRP Ledger Mainnet.
The differences between a CTID and a transaction's [identifying hash](../../../concepts/transactions/index.md#identifying-transactions) are as follows:
- A CTID identifies a validated transaction based on its network ID, ledger index, and position within the ledger. Since it specifies which network a transaction has been validated on, it can be used in contexts where you are interacting with more than one network, such as connecting to sidechains. A CTID is 64 bits, typically written as 16 characters of uppercase hexadecimal starting with `C`, for example `C005523E00000000`.
- An transaction's identifying hash identifies a signed transaction based on its contents, regardless of if that transaction has been validated on any chains. Since it's a cryptographic hash, it can also be used to prove that the transaction contents are intact. A transaction hash is 256 bits, typically written as 64 characters of hexadecimal, for example `E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7`.
**Caution:** Do not try to use a CTID for a transaction that has not yet been validated. The canonical order of the transaction can change between when the transaction is initially applied and when it is validated by the consensus process, resulting in a CTID that identifies a different transaction or no transaction at all.
## Structure
A CTID contains the following parts, in order (big-endian):
1. 4 bits: The hex nibble `C` indicating that this is a CTID.
2. 28 bits: The ledger index of the ledger where the transaction was validated.
3. 16 bits: The transaction index, its place within the ledger's canonical order. This is provided as the field `TransactionIndex` in [transaction metadata](../../protocol/transactions/metadata.md).
4. 16 bits: The [network ID](../../protocol/transactions/common-fields.md#networkid-field) of the network that validated this transaction.
**Note:** The ledger index is normally stored as a 32-bit unsigned integer which increases by 1 each time a new ledger is created. If a network's ledger index is greater than 268,435,455, it won't fit in 28 bits, so the leading `C` should be incremented to `D`, `E`, or `F` as necessary. This is not expected to be necessary until at least the year 2043.
## See Also
For more information including sample code and background, see the [XLS-37d Standard](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0037d-concise-transaction-identifier-ctid).

126
docs/references/http-websocket-apis/api-conventions/error-formatting.md Normal file
View File

@@ -0,0 +1,126 @@
---
html: error-formatting.html
parent: api-conventions.html
seo:
description: Error formats and common error codes for WebSocket, JSON-RPC, and Commandline interfaces.
labels:
- Development
---
# Error Formatting
It is impossible to list all the possible ways an error can occur. Some may occur in the transport layer (for example, loss of network connectivity), in which case the results vary depending on what client and transport you are using. However, if the `rippled` server successfully receives your request, it tries to respond in a standardized error format.
**Caution:** When your request results in an error, the entire request is copied back as part of the response, so that you can try to debug the error. However, this also includes any secrets that were passed as part of the request. When sharing error messages, be very careful not to accidentally expose important account secrets to others.
Some example errors:
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 3,
"status": "error",
"type": "response",
"error": "ledgerIndexMalformed",
"request": {
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"command": "account_info",
"id": 3,
"ledger_index": "-",
"strict": true
}
}
```
{% /tab %}
{% tab label="JSON-RPC" %}
```json
HTTP Status: 200 OK
{
"result": {
"error": "ledgerIndexMalformed",
"request": {
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"command": "account_info",
"ledger_index": "-",
"strict": true
},
"status": "error"
}
}
```
{% /tab %}
{% tab label="Commandline" %}
```json
{
"result": {
"error": "ledgerIndexMalformed",
"request": {
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"command": "account_info",
"ledger_index": "-",
"strict": true
},
"status": "error"
}
}
```
{% /tab %}
{% /tabs %}
## WebSocket Format
| `Field` | Type | Description |
|:----------|:---------|:------------------------------------------------------|
| `id` | (Varies) | ID provided in the Web Socket request that prompted this response |
| `status` | String | `"error"` if the request caused an error |
| `type` | String | Typically `"response"`, which indicates a successful response to a command. |
| `error` | String | A unique code for the type of error that occurred |
| `request` | Object | A copy of the request that prompted this error, in JSON format. **Caution:** If the request contained any secrets, they are copied here! |
| `api_version` | Number | _(May be omitted)_ The `api_version` specified in the request, if any. |
## JSON-RPC Format
Some JSON-RPC request respond with an error code on the HTTP layer. In these cases, the response is a plain-text explanation in the response body. For example, if you forgot to specify the command in the `method` parameter, the response is like this:
```
HTTP Status: 400 Bad Request
Null method
```
For other errors that returned with HTTP status code 200 OK, the responses are formatted in JSON, with the following fields:
| `Field` | Type | Description |
|:-----------------|:-------|:-------------------------------------------------|
| `result` | Object | Object containing the response to the query |
| `result.error` | String | A unique code for the type of error that occurred |
| `result.status` | String | `"error"` if the request caused an error |
| `result.request` | Object | A copy of the request that prompted this error, in JSON format. **Caution:** If the request contained any account secrets, they are copied here! **Note:** The request is re-formatted in WebSocket format, regardless of the request made. |
## Universal Errors
All methods can potentially return any of the following values for the `error` code:
- `amendmentBlocked` - The server is [amendment blocked](../../../concepts/networks-and-servers/amendments.md#amendment-blocked-servers) and needs to be updated to the latest version to stay synced with the XRP Ledger network.
- `failedToForward` - ([Reporting Mode][] servers only) The server tried to forward this request to a P2P Mode server, but the connection failed.
- `invalid_API_version` - The server does not support the [API version number](request-formatting.md#api-versioning) from the request.
- `jsonInvalid` - (WebSocket only) The request is not a proper JSON object.
- JSON-RPC returns a 400 Bad Request HTTP error in this case instead.
- `missingCommand` - (WebSocket only) The request did not specify a `command` field.
- JSON-RPC returns a 400 Bad Request HTTP error in this case instead.
- `noClosed` - The server does not have a closed ledger, typically because it has not finished starting up.
- `noCurrent` - The server does not know what the current ledger is, due to high load, network problems, validator failures, incorrect configuration, or some other problem.
- `noNetwork` - The server is having trouble connecting to the rest of the XRP Ledger peer-to-peer network (and is not running in stand-alone mode).
- `tooBusy` - The server is under too much load to do this command right now. Generally not returned if you are connected as an admin.
- `unknownCmd` - The request does not contain a [command](../index.md) that the `rippled` server recognizes.
- `wsTextRequired` - (WebSocket only) The request's [opcode](https://tools.ietf.org/html/rfc6455#section-5.2) is not text. <!-- SPELLING_IGNORE: opcode -->
{% raw-partial file="/_snippets/common-links.md" /%}

16
docs/references/http-websocket-apis/api-conventions/index.md Normal file
View File

@@ -0,0 +1,16 @@
---
html: api-conventions.html
parent: http-websocket-apis.html
seo:
description: Common conventions used across the XRP Ledger's HTTP APIs.
metadata:
indexPage: true
---
# API Conventions
This section describes data types and formats of the HTTP APIs (JSON-RPC and WebSocket) as implemented in [the `rippled` server](../../../concepts/networks-and-servers/index.md).
For information on the XRP Ledger protocol that applies to all APIs, see [Protocol Reference](../../protocol/index.md).
{% child-pages /%}

23
docs/references/http-websocket-apis/api-conventions/markers-and-pagination.md Normal file
View File

@@ -0,0 +1,23 @@
---
html: markers-and-pagination.html
parent: api-conventions.html
seo:
description: Convention for paginating large queries into multiple responses.
---
# Markers and Pagination
Some methods return more data than can efficiently fit into one response. When there are more results than contained, the response includes a `marker` field. You can use this to retrieve more pages of data across multiple calls. In each request, pass the `marker` value from the previous response to resume from the point where you left off. If the `marker` is omitted from a response, then you have reached the end of the data set.
The format of the `marker` field is intentionally undefined. Each server can define a `marker` field as desired, so it may take the form of a string, a nested object, or another type. Different servers, and different methods provided by the same server, can have different `marker` definitions. Each `marker` is ephemeral, and may not work as expected after 10 minutes.
{% tabs %}
{% tab label="Python" %}
{% code-snippet file="/_code-samples/markers-and-pagination/py/pagination-with-markers.py" language="py" /%}
{% /tab %}
{% tab label="JavaScript" %}
{% code-snippet file="/_code-samples/markers-and-pagination/js/pagination-with-markers.js" language="js" /%}
{% /tab %}
{% /tabs %}

67
docs/references/http-websocket-apis/api-conventions/rate-limiting.md Normal file
View File

@@ -0,0 +1,67 @@
---
html: rate-limiting.html
parent: api-conventions.html
seo:
description: Information on how public APIs limit clients from making too many requests.
labels:
- Core Server
---
# Rate Limiting
The `rippled` server limits the rate at which API clients can make requests on public APIs. Rate limiting is based on the IP address of the client, so clients behind [network address translation](https://en.wikipedia.org/wiki/Network_address_translation) share a limit based on their public IP address.
**Tip:** Rate limiting does not apply when the client is connected [as an admin](../../../tutorials/get-started/get-started-using-http-websocket-apis.md#admin-access).
When a client is approaching the rate limit, the server adds the field `"warning": "load"` at the top level of an [API response](response-formatting.md). This warning is not added to every response, but the server may send several such warnings before it disconnects a client.
If a client goes past the rate limit, the server disconnects that client and does not serve further requests from the client's API address for a while. The WebSocket and JSON-RPC APIs use different disconnect messages.
## WebSocket API Disconnect Message
For the WebSocket API, the server closes the connection and provides a close message and code. The way you access these messages depends on your WebSocket client implementation. For example, using the [Node.js ws library](https://github.com/websockets/ws), the following code prints the close reason when disconnected:
```js
const WebSocket = require('ws')
const ws = new WebSocket('ws://localhost:6007/')
ws.on('close', (code,reason) => {
console.log("Disconnected. \ncode: ", code, "\nreason: ", reason)
})
// If rate limited, prints:
// Disconnected.
// code: 1008
// reason: threshold exceeded
```
If the connection is closed because of rate limiting, the close code is `1008` and the close message is the string `threshold exceeded`.
## JSON-RPC Rate Limited Error
For a JSON-RPC API request, the server responds with the HTTP status code **503 Service Unavailable** when the client is over the rate limit. This response has a text (not JSON) body stating that the server is overloaded:
```text
503 Service Unavailable
Server is overloaded
```
## Rate Per Request
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/resource/Fees.h "Source")
The server calculates a client's usage rate based on the number of requests made over time, and weighs different types of requests based on approximately how much work the server must do to serve them. Follow-up messages from the server for the [subscribe method][] and [path_find method][] also count towards a client's usage rate.
The usage rate drops off exponentially over time, so a client that does not make requests automatically has its access restored after a period of seconds to minutes.
## See Also
- **Concepts:**
- [The `rippled` Server](../../../concepts/networks-and-servers/index.md)
- [Software Ecosystem](../../../introduction/software-ecosystem.md)
- **Tutorials:**
- [Getting Started with XRP Ledger APIs](../../../tutorials/get-started/get-started-using-http-websocket-apis.md)
- [Troubleshooting rippled](../../../infrastructure/troubleshooting/index.md)
- **References:**
- [rippled API Reference](../index.md)
- [Error Formatting](error-formatting.md)
{% raw-partial file="/_snippets/common-links.md" /%}

140
docs/references/http-websocket-apis/api-conventions/request-formatting.md Normal file
View File

@@ -0,0 +1,140 @@
---
html: request-formatting.html
parent: api-conventions.html
seo:
description: Standard request format, with examples, for the WebSocket, JSON-RPC, and Commandline interfaces.
---
# Request Formatting
## Example Request
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 2,
"command": "account_info",
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"strict": true,
"ledger_index": "validated",
"api_version": 1
}
```
{% /tab %}
{% tab label="JSON-RPC" %}
```json
POST http://s1.ripple.com:51234/
Content-Type: application/json
{
"method": "account_info",
"params": [
{
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"strict": true,
"ledger_index": "validated",
"api_version": 1
}
]
}
```
{% /tab %}
{% tab label="Commandline" %}
```sh
rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated strict
```
{% /tab %}
{% /tabs %}
## WebSocket Format
After you open a WebSocket to the `rippled` server, you can send commands as a [JSON](https://en.wikipedia.org/wiki/JSON) object with the following fields:
| Field | Type | Description |
|:--------------------|:----------|:-------------------------------------------|
| `command` | String | The name of the [API method](../public-api-methods/index.md). |
| `id` | (Various) | _(Optional)_ A unique value to identify this request. The response to this request uses the same `id` field. This way, even if responses arrive out of order, you know which request prompted which response. |
| `api_version` | Number | _(Optional)_ The API version to use. If omitted, use version 1. For details, see [API Versioning](#api-versioning). |
| (Method Parameters) | (Various) | Provide any parameters to the method at the top level. |
See [Response Formatting](response-formatting.md) for the response from the server.
## JSON-RPC Format
To make a JSON-RPC request, send an HTTP **POST** request to the root path (`/`) on the port and IP where the `rippled` server is listening for JSON-RPC connections. You can use HTTP/1.0 or HTTP/1.1. If you use HTTPS, you should use TLS version 1.2. For security reasons, `rippled` _does not support_ SSL version 3 or earlier.
Always include a `Content-Type` header with the value `application/json`.
If you plan on making multiple requests, use [Keep-Alives](http://tools.ietf.org/html/rfc7230#section-6.3) so that you do not have to close and re-open the connection in between requests. <!-- SPELLING_IGNORE: alives -->
Send request body as a [JSON](https://en.wikipedia.org/wiki/JSON) object with the following fields:
| Field | Type | Description |
|:--------------------|:----------|:-------------------------------------------|
| `method` | String | The name of the [API method](../public-api-methods/index.md). |
| `params` | Array | _(Optional)_ A **one-item array** containing a nested JSON object with the parameters to this method. You may omit this field if the method does not require any parameters. |
The object inside the `params` array can contain the following fields:
| Field | Type | Description |
|:--------------------|:----------|:-------------------------------------------|
| `api_version` | Number | _(Optional)_ The API version to use. If omitted, uses version `1`. For details, see [API Versioning](#api-versioning). |
| (Method Parameters) | (Various) | Provide any parameters to the method here. |
See [Response Formatting](response-formatting.md) for the response from the server.
## Commandline Format
Put the API method name after any normal (dash-prefaced) commandline options, followed by a limited set of parameters, separated by spaces. For any parameter values that might contain spaces or other unusual characters, use single-quotes to encapsulate them. Not all methods have commandline API syntax. For more information, see [Commandline Usage](../../../infrastructure/commandline-usage.md#client-mode-options).
The commandline calls JSON-RPC, so its responses always match the JSON-RPC [response format](response-formatting.md).
The commandline always uses the latest [API version](#api-versioning).
**Caution:** The commandline interface is intended for administrative purposes only and is _not a supported API_. New versions of `rippled` may introduce breaking changes to the commandline API without warning!
## API Versioning
The `rippled` server uses a single integer to identify the API version to use. Currently, there are two API versions: `1` and `2` {% badge href="https://github.com/XRPLF/rippled/releases/tag/2.0.0" %}New in: rippled 2.0.0{% /badge %}. The server reports the range of supported API versions in the `version` API method. <!-- STYLE_OVERRIDE: will --> <!-- TODO: add a link when `version` method is documented. -->
Separate API requests can use different API versions even on the same persistent connection. For example, if you connect WebSocket to a server that supports API versions 1 and 2, you can make an `account_tx` request using API version 2 and then make another `account_tx` request using API version 1 from the same connection.
Future versions of `rippled` that introduce breaking changes will introduce a new API version 3.
### Breaking Changes
The following types of changes are **breaking changes**:
- Removing or renaming a field of a request or response.
- Changing the type of a field of a request or response.
- Changing the meaning of a field of a request or a response.
- Changing the order of positional parameters, or adding a new field before other positional parameters.
- Removing or renaming an API method.
- Changing the behavior of an API function visible to existing clients.
- The following types of breaking changes only apply to the gRPC API:
- Changing a `proto` field number.
- Removing or renaming an enum or enum value.
- Adding or removing fields from a `oneof`.
- Splitting or merging a `oneof`.
- Changing whether a message field is `optional`, `repeated`, or `required`.
- Changing the stream value of a request or response.
- Deleting or renaming a package or service.
Any time a full release introduces a breaking change, it introduces a new API version number. Pre-release, beta, and development versions may introduce breaking changes to the same API version number.
### Non-Breaking Changes
The following types of changes are **non-breaking changes** and may occur without a change of API version number:
- Adding a new field to a request or response, not including positional parameters.
- Adding a new API method.
{% raw-partial file="/_snippets/common-links.md" /%}

199
docs/references/http-websocket-apis/api-conventions/response-formatting.md Normal file
View File

@@ -0,0 +1,199 @@
---
html: response-formatting.html
parent: api-conventions.html
seo:
description: Standard response format, with examples, for the WebSocket, JSON-RPC, and Commandline interfaces.
---
# Response Formatting
Responses are formatted slightly differently based on whether the method is called with the WebSocket, JSON-RPC, or Commandline interfaces. The Commandline and JSON-RPC interfaces use the same format because the Commandline interface calls JSON-RPC.
The fields of a successful response include:
| `Field` | Type | Description |
|:----------------|:---------|:------------------------------------------------|
| `id` | (Varies) | (WebSocket only) ID provided in the request that prompted this response |
| `status` | String | (WebSocket only) The value `success` indicates the request was successfully received and understood by the server. Some [client libraries](../../client-libraries.md) omit this field on success. |
| `result.status` | String | (JSON-RPC and Commandline) The value `success` indicates the request was successfully received and understood by the server. Some [client libraries](../../client-libraries.md) omit this field on success. |
| `type` | String | (WebSocket only) The value `response` indicates a direct response to an API request. [Asynchronous notifications](../public-api-methods/subscription-methods/subscribe.md) use a different value such as `ledgerClosed` or `transaction`. |
| `result` | Object | The result of the query; contents vary depending on the command. |
| `warning` | String | _(May be omitted)_ If this field is provided, the value is the string `load`. This means the client is approaching the [rate limiting](rate-limiting.md) threshold where the server will disconnect this client. <!-- STYLE_OVERRIDE: will --> |
| `warnings` | Array | _(May be omitted)_ If this field is provided, it contains one or more **Warnings Objects** with important warnings. For details, see [API Warnings](#api-warnings). |
| `forwarded` | Boolean | _(May be omitted)_ If `true`, this request and response have been forwarded from a [Reporting Mode][] server to a P2P Mode server (and back) because the request requires data that is not available in Reporting Mode. The default is `false`. |
## Example Successful Response
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 2,
"status": "success",
"type": "response",
"result": {
"account_data": {
"Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"Balance": "27389517749",
"Flags": 0,
"LedgerEntryType": "AccountRoot",
"OwnerCount": 18,
"PreviousTxnID": "B6B410172C0B65575D89E464AF5B99937CC568822929ABF87DA75CBD11911932",
"PreviousTxnLgrSeq": 6592159,
"Sequence": 1400,
"index": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05"
},
"ledger_index": 6760970
}
}
```
{% /tab %}
{% tab label="JSON-RPC" %}
```json
HTTP Status: 200 OK
{
"result": {
"account_data": {
"Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"Balance": "27389517749",
"Flags": 0,
"LedgerEntryType": "AccountRoot",
"OwnerCount": 18,
"PreviousTxnID": "B6B410172C0B65575D89E464AF5B99937CC568822929ABF87DA75CBD11911932",
"PreviousTxnLgrSeq": 6592159,
"Sequence": 1400,
"index": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05"
},
"ledger_index": 6761012,
"status": "success"
}
}
```
{% /tab %}
{% tab label="Commandline" %}
```json
{
"result": {
"account_data": {
"Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"Balance": "27389517749",
"Flags": 0,
"LedgerEntryType": "AccountRoot",
"OwnerCount": 18,
"PreviousTxnID": "B6B410172C0B65575D89E464AF5B99937CC568822929ABF87DA75CBD11911932",
"PreviousTxnLgrSeq": 6592159,
"Sequence": 1400,
"index": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05"
},
"ledger_index": 6761012,
"status": "success"
}
}
```
{% /tab %}
{% /tabs %}
## API Warnings
When the response contains a `warnings` array, each member of the array represents a separate warning from the server. Each such **Warning Object** contains the following fields:
| `Field` | Type | Description |
|:----------|:-------|:--------------------------------------------------------|
| `id` | Number | A unique numeric code for this warning message. |
| `message` | String | A human-readable string describing the cause of this message. Do not write software that relies the contents of this message; use the `id` (and `details`, if applicable) to identify the warning instead. |
| `details` | Object | _(May be omitted)_ Additional information about this warning. The contents vary depending on the type of warning. |
The following reference describes all possible warnings.
### 1001. Unsupported amendments have reached majority
Example warning:
```json
"warnings" : [
{
"details" : {
"expected_date" : 864030,
"expected_date_UTC" : "2000-Jan-11 00:00:30.0000000 UTC"
},
"id" : 1001,
"message" : "One or more unsupported amendments have reached majority. Upgrade to the latest version before they are activated to avoid being amendment blocked."
}
]
```
This warning indicates that the one or more [amendments](../../../concepts/networks-and-servers/amendments.md) to the XRP Ledger protocol are scheduled to become enabled, but the current server does not have an implementation for those amendments. If those amendments become enabled, the current server will become [amendment blocked](../../../concepts/networks-and-servers/amendments.md#amendment-blocked-servers), so you should [upgrade to the latest `rippled` version](../../../infrastructure/installation/index.md) as soon as possible. <!-- STYLE_OVERRIDE: will -->
The server only sends this warning if the client is [connected as an admin](../../../tutorials/get-started/get-started-using-http-websocket-apis.md#admin-access).
This warning includes a `details` field with the following fields:
| Field | Value | Description |
|:--------------------|:-------|:----------------------------------------------|
| `expected_date` | Number | The time that the first unsupported amendment is expected to become enabled, in [seconds since the Ripple Epoch][]. |
| `expected_date_UTC` | String | The timestamp, in UTC, when the first unsupported amendment is expected to become enabled. |
Due to the variation in ledger close times, these times are approximate. It is also possible that the amendment fails to maintain support from >80% of validators until the specified time, and does not become enabled at the expected time. The server will not become amendment blocked so long as the unsupported amendments do not become enabled.
### 1002. This server is amendment blocked
Example warning:
```json
"warnings" : [
{
"id" : 1002,
"message" : "This server is amendment blocked, and must be updated to be able to stay in sync with the network."
}
]
```
This warning indicates that the server is [amendment blocked](../../../concepts/networks-and-servers/amendments.md#amendment-blocked-servers) and can no longer remain synced with the XRP Ledger.
The server administrator must [upgrade `rippled`](../../../infrastructure/installation/index.md) to a version that supports the activated amendments.
### 1003. This is a reporting server
Example warning:
```json
"warnings" : [
{
"id" : 1003,
"message" : "This is a reporting server. The default behavior of a reporting server is to only return validated data. If you are looking for not yet validated data, include \"ledger_index : current\" in your request, which will cause this server to forward the request to a p2p node. If the forward is successful the response will include \"forwarded\" : \"true\""
}
]
```
This warning indicates that the server answering the request is running [Reporting Mode][]. Certain API methods are not available or behave differently because Reporting Mode does not connect to the peer-to-peer network and does not track ledger data that has not yet been validated.
It is generally safe to ignore this warning.
**Caution:** If you request ledger data without explicitly [specifying a ledger version][Specifying Ledgers], Reporting Mode uses the latest validated ledger by default instead of the current in-progress ledger.
## See Also
- [Request Formatting](request-formatting.md)
- [Error Formatting](error-formatting.md) for unsuccessful API responses.
- **Concepts:**
- [The `rippled` Server](../../../concepts/networks-and-servers/index.md)
- [Consensus](../../../concepts/consensus-protocol/index.md)
- [Amendments](../../../concepts/networks-and-servers/amendments.md)
- [Known Amendments](../../../resources/known-amendments.md)
- **Tutorials:**
- [Get Started with XRP Ledger APIs](../../../tutorials/get-started/get-started-using-http-websocket-apis.md)
- [Install and Update `rippled`](../../../infrastructure/installation/index.md)
- **References:**
- [feature method][]
- [server_info method][]
{% raw-partial file="/_snippets/common-links.md" /%}

25
docs/references/http-websocket-apis/api-conventions/rippled-server-states.md Normal file
View File

@@ -0,0 +1,25 @@
---
html: rippled-server-states.html
parent: api-conventions.html
seo:
description: Definitions of state information reported in some API methods.
labels:
- Core Server
---
# rippled Server States
Depending on how the `rippled` server is configured, how long it has been running, and other factors, a server may be participating in the global XRP Ledger peer-to-peer network to different degrees. This is represented as the `server_state` field in the responses to the [server_info method][] and [server_state method][]. The possible responses follow a range of ascending interaction, with each later value superseding the previous one. Their definitions are as follows (in order of increasing priority):
| `Value` | Description |
|:---------------|:------------------------------------------------------------|
| `disconnected` | The server is not connected to the XRP Ledger peer-to-peer network whatsoever. It may be running in offline mode, or it may not be able to access the network for whatever reason. |
| `connected` | The server believes it is connected to the network. |
| `syncing` | The server is currently behind on ledger versions. (It is normal for a server to spend a few minutes catching up after you start it.) |
| `tracking` | The server is in agreement with the network |
| `full` | The server is fully caught-up with the network and could participate in validation, but is not doing so (possibly because it has not been configured as a validator). |
| `validating` | The server is currently participating in validation of the ledger |
| `proposing` | The server is participating in validation of the ledger and currently proposing its own version. |
**Note:** The distinction between `full`, `validating`, and `proposing` is based on synchronization with the rest of the global network, and it is normal for a server to fluctuate between these states as a course of general operation.
{% raw-partial file="/_snippets/common-links.md" /%}