# Get conversion

Returns one confirmed conversion, including its status, sell and buy accounts, amounts, locked rate, and fee.
An unconfirmed `PENDING` conversion is available only in the create response.

Product: Direct Trade API
API reference version: 0.1.0 (current)
OpenAPI contract: https://docs.axiym.io/openapi/direct-trade-api/0.1.0.yaml
Canonical page: https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/conversions/getConversion

[Compact reference](/direct-trade-api/api-reference/0.1.0/conversions/getConversion.md)

## GET /conversions/{conversionId}

## Servers

```json
[
  {
    "url": "https://partner-api.sandbox.axiym.io/api/v1",
    "description": "Sandbox"
  },
  {
    "url": "https://partner-api.axiym.io/api/v1",
    "description": "Production"
  }
]
```

## Authentication

```json
{
  "security": [
    {
      "Default": []
    }
  ],
  "securitySchemes": {
    "Default": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    }
  }
}
```

## Parameters

### path: conversionId

```json
{
  "name": "conversionId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "a3f5d7c9-1e2b-4c6a-8d9f-0b1a2c3d4e5f"
    ]
  },
  "description": "Conversion identifier (UUID)."
}
```

### header: X-Request-Id

```json
{
  "name": "X-Request-Id",
  "in": "header",
  "required": false,
  "description": "Optional identifier for tracing a request end to end. A UUID is recommended. Axiym returns it in the `X-Request-Id` response header and records it in logs. If omitted, Axiym generates one. Include it when contacting support.\n",
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }
}
```

## Responses

### 200

```json
{
  "description": "Conversion.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Conversion"
      },
      "examples": {
        "USD to USDT": {
          "summary": "USD → USDT, completed",
          "value": {
            "conversionId": "a3f5d7c9-1e2b-4c6a-8d9f-0b1a2c3d4e5f",
            "pairId": "7c9e1a3b-5d2f-4e8a-9b0c-6d4f2a8e1c3b",
            "status": "COMPLETED",
            "sellAccount": {
              "accountId": "5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e",
              "currency": "USD",
              "paymentRails": "ZENUS_BANK"
            },
            "sellAmount": {
              "amount": "10000.00",
              "currency": "USD"
            },
            "buyAccount": {
              "accountId": "8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a",
              "currency": "USDT",
              "paymentRails": "TRON"
            },
            "buyAmount": {
              "amount": "9985.00",
              "currency": "USDT"
            },
            "rate": "1.00",
            "fee": {
              "amount": "15.00",
              "currency": "USD"
            },
            "externalReference": "conv-2026-0714-01",
            "createdAt": "2026-07-14T14:00:11Z",
            "completedAt": "2026-07-14T14:05:39Z"
          }
        },
        "USDT to USD": {
          "summary": "USDT → USD, completed",
          "value": {
            "conversionId": "b8e6c2a4-5d1f-4e9b-a7c3-6f2d8b0a4e1c",
            "pairId": "2b8d0c4e-6f1a-4d3c-8e5b-9a7c3f0d2e4a",
            "status": "COMPLETED",
            "sellAccount": {
              "accountId": "8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a",
              "currency": "USDT",
              "paymentRails": "TRON"
            },
            "sellAmount": {
              "amount": "5000.00",
              "currency": "USDT"
            },
            "buyAccount": {
              "accountId": "5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e",
              "currency": "USD",
              "paymentRails": "ZENUS_BANK"
            },
            "buyAmount": {
              "amount": "4992.50",
              "currency": "USD"
            },
            "rate": "1.00",
            "fee": {
              "amount": "7.50",
              "currency": "USD"
            },
            "externalReference": "conv-2026-0714-02",
            "createdAt": "2026-07-14T14:05:44Z",
            "completedAt": "2026-07-14T14:11:02Z"
          }
        }
      }
    }
  }
}
```

### 400

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "message": {
                "type": "string"
              }
            },
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Malformed JSON body": {
          "summary": "Malformed JSON body",
          "value": {
            "code": 400,
            "message": "Bad Request",
            "errors": {
              "message": "Failed to parse the request body as JSON: expected value at line 1 column 5"
            }
          }
        },
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 400,
            "message": "Invalid cursor",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 401

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 401,
            "message": "Unauthorized",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 403

```json
{
  "description": "Forbidden",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 403,
            "message": "Forbidden",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 404

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message: either the generic 'Not Found' or a domain-specific one such as 'Account Not Found'."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 404,
            "message": "Not Found",
            "errors": null
          }
        },
        "Account not found": {
          "summary": "Account not found",
          "value": {
            "code": 404,
            "message": "Account Not Found",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 422

```json
{
  "description": "The request failed validation or a business rule. Validation failures return `errors` keyed by request field. Business rejections return `errors: null` and explain the reason in `message`.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "`Invalid Parameters` for validation failures; the rejection reason otherwise."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "For validation failures, keys follow the request fields and values contain field errors or nested errors. Business rejections return `null`.",
            "additionalProperties": {
              "$ref": "#/components/schemas/ValidationFieldErrors"
            }
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Flat field errors": {
          "summary": "Flat field errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "legalEntityName": [
                {
                  "code": "length",
                  "message": null,
                  "params": {
                    "value": "",
                    "min": 1
                  }
                }
              ],
              "currency": [
                {
                  "code": "invalid_currency",
                  "message": null,
                  "params": {
                    "value": "ZZZ"
                  }
                }
              ]
            }
          }
        },
        "Nested struct errors": {
          "summary": "Nested struct errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "legalAddress": {
                "country": [
                  {
                    "code": "invalid_country",
                    "message": null,
                    "params": {
                      "value": "INVALID"
                    }
                  }
                ],
                "postalCode": [
                  {
                    "code": "length",
                    "message": null,
                    "params": {
                      "value": "",
                      "min": 1
                    }
                  }
                ]
              }
            }
          }
        },
        "List item errors": {
          "summary": "List item errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "authorizedDirectors": {
                "0": {
                  "firstName": [
                    {
                      "code": "length",
                      "message": null,
                      "params": {
                        "value": "",
                        "min": 1
                      }
                    }
                  ],
                  "email": [
                    {
                      "code": "email",
                      "message": null,
                      "params": {
                        "value": "not-an-email"
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "Custom validator": {
          "summary": "Custom validator",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "disbursementAccount": [
                {
                  "code": "disbursement_account_required",
                  "message": null,
                  "params": {
                    "value": null
                  }
                }
              ]
            }
          }
        },
        "Business rejection": {
          "summary": "Business rejection",
          "value": {
            "code": 422,
            "message": "Documents Not Accepted",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 500

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 500,
            "message": "Internal Error",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

## Operation metadata

```json
{
  "tags": [
    "Conversions"
  ],
  "operationId": "getConversion"
}
```

## Referenced definitions

- [`#/components/parameters/ConversionId`](#definition-1)
- [`#/components/parameters/RequestId`](#definition-2)
- [`#/components/schemas/Conversion`](#definition-3)
- [`#/components/schemas/ConversionStatus`](#definition-4)
- [`#/components/schemas/AccountRef`](#definition-5)
- [`#/components/schemas/Currency`](#definition-6)
- [`#/components/schemas/PaymentRailsCode`](#definition-7)
- [`#/components/schemas/Money`](#definition-8)
- [`#/components/schemas/Decimal`](#definition-9)
- [`#/components/schemas/ExternalReference`](#definition-10)
- [`#/components/responses/BadRequest`](#definition-11)
- [`#/components/responses/Unauthorized`](#definition-12)
- [`#/components/responses/Forbidden`](#definition-13)
- [`#/components/responses/NotFound`](#definition-14)
- [`#/components/responses/InvalidParams`](#definition-15)
- [`#/components/schemas/ValidationFieldErrors`](#definition-16)
- [`#/components/schemas/ValidationError`](#definition-17)
- [`#/components/responses/InternalError`](#definition-18)

### definition-1

`#/components/parameters/ConversionId`

```json
{
  "name": "conversionId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "a3f5d7c9-1e2b-4c6a-8d9f-0b1a2c3d4e5f"
    ]
  },
  "description": "Conversion identifier (UUID)."
}
```

### definition-2

`#/components/parameters/RequestId`

```json
{
  "name": "X-Request-Id",
  "in": "header",
  "required": false,
  "description": "Optional identifier for tracing a request end to end. A UUID is recommended. Axiym returns it in the `X-Request-Id` response header and records it in logs. If omitted, Axiym generates one. Include it when contacting support.\n",
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }
}
```

### definition-3

`#/components/schemas/Conversion`

```json
{
  "type": "object",
  "required": [
    "conversionId",
    "pairId",
    "status",
    "sellAccount",
    "sellAmount",
    "buyAccount",
    "buyAmount",
    "rate",
    "fee",
    "createdAt"
  ],
  "properties": {
    "conversionId": {
      "type": "string",
      "format": "uuid",
      "description": "Conversion identifier (UUID).",
      "examples": [
        "a3f5d7c9-1e2b-4c6a-8d9f-0b1a2c3d4e5f"
      ]
    },
    "pairId": {
      "type": "string",
      "format": "uuid",
      "description": "The conversion pair this conversion runs along.",
      "examples": [
        "7c9e1a3b-5d2f-4e8a-9b0c-6d4f2a8e1c3b"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/ConversionStatus",
      "description": "Conversion status.",
      "examples": [
        "COMPLETED"
      ]
    },
    "reasonCode": {
      "type": "string",
      "description": "Present when `status` is `CANCELED` — the reason as reported by operations or the liquidity venue. Example: `RATE_EXPIRED`."
    },
    "sellAccount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/AccountRef"
        }
      ],
      "description": "The sell-side account, embedded as a compact reference."
    },
    "sellAmount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Amount sold, in the sell currency."
    },
    "buyAccount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/AccountRef"
        }
      ],
      "description": "The buy-side account, embedded as a compact reference."
    },
    "buyAmount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Amount bought and credited to the buy-side account."
    },
    "rate": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Decimal"
        }
      ],
      "description": "Units of buy currency received for one unit of sell currency.",
      "examples": [
        "1.00"
      ]
    },
    "fee": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Fee charged, in the ISO 4217 currency of the pair. It is deducted from the sell amount when buying digital currency and from the buy proceeds when selling it."
    },
    "externalReference": {
      "$ref": "#/components/schemas/ExternalReference",
      "description": "Your reference for correlation, echoed back on related objects.",
      "examples": [
        "conv-2026-0714-01"
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Creation timestamp. Formatted in ISO 8601.",
      "examples": [
        "2026-07-14T14:00:11Z"
      ]
    },
    "completedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Completion timestamp. Formatted in ISO 8601.",
      "examples": [
        "2026-07-14T14:05:39Z"
      ]
    }
  }
}
```

### definition-4

`#/components/schemas/ConversionStatus`

```json
{
  "type": "string",
  "description": "`PENDING` awaits confirmation and appears only in the create response. `ACTIVE` is executing. `COMPLETED` means the funds were exchanged. `CANCELED` means the conversion stopped; see `reasonCode`.\n",
  "enum": [
    "PENDING",
    "ACTIVE",
    "COMPLETED",
    "CANCELED"
  ],
  "examples": [
    "PENDING"
  ]
}
```

### definition-5

`#/components/schemas/AccountRef`

```json
{
  "type": "object",
  "description": "Compact account reference. Fetch the account via `GET /accounts/{accountId}` for the current balance and status; deposit instructions serve its payment details.",
  "required": [
    "accountId",
    "currency",
    "paymentRails"
  ],
  "properties": {
    "accountId": {
      "type": "string",
      "format": "uuid",
      "description": "Account identifier (UUID).",
      "examples": [
        "5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Account currency.",
      "examples": [
        "USD"
      ]
    },
    "paymentRails": {
      "$ref": "#/components/schemas/PaymentRailsCode",
      "description": "Rail the account settles on.",
      "examples": [
        "ZENUS_BANK"
      ]
    }
  }
}
```

### definition-6

`#/components/schemas/Currency`

```json
{
  "type": "string",
  "description": "Currency code — ISO 4217 (e.g. USD, EUR) or a supported digital currency (USDT, USDC).",
  "examples": [
    "USD"
  ]
}
```

### definition-7

`#/components/schemas/PaymentRailsCode`

```json
{
  "type": "string",
  "description": "Payment rail code the account settles on (e.g. `ZENUS_BANK`, `TRON`).",
  "examples": [
    "ZENUS_BANK"
  ]
}
```

### definition-8

`#/components/schemas/Money`

```json
{
  "type": "object",
  "description": "Monetary amount and its currency.",
  "additionalProperties": false,
  "required": [
    "amount",
    "currency"
  ],
  "properties": {
    "amount": {
      "$ref": "#/components/schemas/Decimal"
    },
    "currency": {
      "$ref": "#/components/schemas/Currency"
    }
  }
}
```

### definition-9

`#/components/schemas/Decimal`

```json
{
  "type": "string",
  "description": "Decimal number serialized as a string to preserve precision. Amounts sent to Axiym are positive and carry at most 8 decimal places.",
  "examples": [
    "1000.00"
  ]
}
```

### definition-10

`#/components/schemas/ExternalReference`

```json
{
  "type": "string",
  "maxLength": 255,
  "description": "Your optional identifier for correlating the resource with your system. Axiym returns it on reads. It does not make retries safe; use `Idempotency-Key` for that.\n",
  "examples": [
    "wd-2026-0714-01"
  ]
}
```

### definition-11

`#/components/responses/BadRequest`

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "message": {
                "type": "string"
              }
            },
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Malformed JSON body": {
          "summary": "Malformed JSON body",
          "value": {
            "code": 400,
            "message": "Bad Request",
            "errors": {
              "message": "Failed to parse the request body as JSON: expected value at line 1 column 5"
            }
          }
        },
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 400,
            "message": "Invalid cursor",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-12

`#/components/responses/Unauthorized`

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 401,
            "message": "Unauthorized",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-13

`#/components/responses/Forbidden`

```json
{
  "description": "Forbidden",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 403,
            "message": "Forbidden",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-14

`#/components/responses/NotFound`

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message: either the generic 'Not Found' or a domain-specific one such as 'Account Not Found'."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 404,
            "message": "Not Found",
            "errors": null
          }
        },
        "Account not found": {
          "summary": "Account not found",
          "value": {
            "code": 404,
            "message": "Account Not Found",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-15

`#/components/responses/InvalidParams`

```json
{
  "description": "The request failed validation or a business rule. Validation failures return `errors` keyed by request field. Business rejections return `errors: null` and explain the reason in `message`.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "`Invalid Parameters` for validation failures; the rejection reason otherwise."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "For validation failures, keys follow the request fields and values contain field errors or nested errors. Business rejections return `null`.",
            "additionalProperties": {
              "$ref": "#/components/schemas/ValidationFieldErrors"
            }
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Flat field errors": {
          "summary": "Flat field errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "legalEntityName": [
                {
                  "code": "length",
                  "message": null,
                  "params": {
                    "value": "",
                    "min": 1
                  }
                }
              ],
              "currency": [
                {
                  "code": "invalid_currency",
                  "message": null,
                  "params": {
                    "value": "ZZZ"
                  }
                }
              ]
            }
          }
        },
        "Nested struct errors": {
          "summary": "Nested struct errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "legalAddress": {
                "country": [
                  {
                    "code": "invalid_country",
                    "message": null,
                    "params": {
                      "value": "INVALID"
                    }
                  }
                ],
                "postalCode": [
                  {
                    "code": "length",
                    "message": null,
                    "params": {
                      "value": "",
                      "min": 1
                    }
                  }
                ]
              }
            }
          }
        },
        "List item errors": {
          "summary": "List item errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "authorizedDirectors": {
                "0": {
                  "firstName": [
                    {
                      "code": "length",
                      "message": null,
                      "params": {
                        "value": "",
                        "min": 1
                      }
                    }
                  ],
                  "email": [
                    {
                      "code": "email",
                      "message": null,
                      "params": {
                        "value": "not-an-email"
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "Custom validator": {
          "summary": "Custom validator",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "disbursementAccount": [
                {
                  "code": "disbursement_account_required",
                  "message": null,
                  "params": {
                    "value": null
                  }
                }
              ]
            }
          }
        },
        "Business rejection": {
          "summary": "Business rejection",
          "value": {
            "code": 422,
            "message": "Documents Not Accepted",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-16

`#/components/schemas/ValidationFieldErrors`

```json
{
  "description": "Nested validation errors keyed by field name or array index. Leaf values are arrays of `ValidationError` objects.",
  "oneOf": [
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ValidationError"
      }
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/ValidationFieldErrors"
      },
      "properties": {}
    }
  ]
}
```

### definition-17

`#/components/schemas/ValidationError`

```json
{
  "type": "object",
  "description": "One field-level validation error.",
  "properties": {
    "code": {
      "type": "string",
      "description": "Validation rule code (e.g. 'length', 'email', 'invalid_currency', 'disbursement_account_required').",
      "examples": [
        "length"
      ]
    },
    "message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Human-readable message.",
      "examples": [
        "string"
      ]
    },
    "params": {
      "type": "object",
      "description": "Rule-specific parameters. Always includes `value` (the offending input). Additional keys depend on the rule (e.g. `min`, `max` for length).",
      "properties": {
        "value": {
          "description": "The submitted value that failed validation.",
          "examples": [
            "string"
          ]
        }
      }
    }
  },
  "required": [
    "code",
    "params"
  ]
}
```

### definition-18

`#/components/responses/InternalError`

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 500,
            "message": "Internal Error",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```