# Identity Document sharing

Share identity documents for KYC verification.
**Use Case**: Submit customer identity documents directly to Banxa for verification.
**Process**:
1. Collect customer information and documents
2. Submit via this endpoint
3. Receive 202 Accepted response
4. Wait for webhook notification with verification result

**Required Documents**:
- At least one government-issued photo ID
- Proof of address (if required)
- Selfie for liveness verification

**Document Quality**:
- Clear, high-resolution images
- All text readable
- No glare or shadows
- Maximum 10MB per image

Endpoint: POST /eapi/v0/identities/share/documents
Version: 0 BETA
Security: HMACAuth

## Security:

  - `HMACAuth` (unknown)
    apiKey in header Authorization

## Request fields (application/json):

  - `identityReference` (string, required)
    A unique customer identifier provided by the partner. This field is required and must be unique for each customer.
**Important**: You must consistently reuse the same identityReference for repeat interactions with the same customer, allowing Banxa to reliably recognize and associate their identity across multiple transactions.
**Format Requirements**:
- Only ASCII letters (a-z, A-Z), digits (0-9), and hyphens (-) are allowed
- Must be between 1 and 255 characters
- Case-sensitive

**Best Practices**:
- Use a consistent format across your system
- Consider using a prefix to identify your organization (e.g., 'partner-customer-123')
- Do not include personally identifiable information (PII) in the reference
- Store the mapping between your internal customer ID and this reference securely
    Example: c-13344

  - `mobileNumber` (string, required)
    Customer's mobile phone number in international format (E.164).
**Format**: Include country code with + prefix
**Examples**:
- "+61431000001" (Australia)
- "+14155552671" (USA)
- "+442071234567" (UK)

**Requirements**:
- Must be a valid, active mobile number
- Used for SMS verification if needed
- Maximum 20 characters
    Example: +61431000001

  - `email` (string, required)
    Customer's email address.
**Requirements**:
- Must be a valid email format
- Used for communication and verification
- Maximum 254 characters (RFC 5321)

**Best Practice**: Use the customer's primary email address
    Example: customer@example.com

  - `customerIdentity` (object, required)

  - `customerIdentity.givenName` (string, required)
    Customer's given / first name.
    Example: Joe

  - `customerIdentity.surname` (string, required)
    Customer's surname / last name.
    Example: Bloggs

  - `customerIdentity.dob` (string, required)
    Customer's date of birth (e.g. "1985-01-31"). Required to format as ISO 8601 Date format : YYYY-MM-DD.
    Example: 1990-01-31

  - `customerIdentity.taxIdType` (string)
    The category of tax or government identifier supplied in `taxId`. The correct value depends on the customer's country and the identifier type accepted for that country.
| Value | Description |
|  --- | --- |
| `identity_card` | A government-issued identity card number used for identity or tax reporting in the customer's country. |
| `tax_id` | A tax identification number issued by a tax authority, such as a TFN, TIN, ITIN, or equivalent. |
| `national_number` | A national, citizen, resident, or social insurance number used to identify an individual in their country. |
| `ssn` | A Social Security Number, generally used for US individuals. |
    Enum: "identity_card", "tax_id", "national_number", "ssn"

  - `customerIdentity.taxId` (string)
    Tax identification number.
See [TIN validation](https://docs.banxa.com/products/native-api/docs/compliance/tin-validation).
    Example: 123-11-123

  - `customerIdentity.taxState` (string)
    Tax state or region if applicable.(associated with the taxId) Required format as two characters. Note; We do not accept any states where Banxa is not licensed.
    Example: IL

  - `customerIdentity.residentialAddress` (object, required)
    Customer's residential address. Required for identity verification and compliance purposes.
**Important**: This must be the customer's current residential address, not a PO Box or business address.

  - `customerIdentity.residentialAddress.addressLine` (string, required)
    Primary street address including street number and name.
**Examples**:
- "44 Gwynne Street"
- "123 Main Street, Apt 4B"
- "10 Downing Street"

**Requirements**:
- Must include street number and name
- Can include unit/apartment number
- Maximum 200 characters
    Example: 44 Gwynne Street

  - `customerIdentity.residentialAddress.suburb` (string, required)
    Suburb, city, or town name.
**Regional Variations**:
- Australia: Suburb (e.g., "Cremorne")
- USA: City (e.g., "New York")
- UK: Town/City (e.g., "London")
- Europe: City (e.g., "Paris")
    Example: Cremorne

  - `customerIdentity.residentialAddress.state` (string, required)
    State, province, or region code.
**Format**: Typically 2-3 character code
**Examples**:
- Australia: "VIC", "NSW", "QLD"
- USA: "CA", "NY", "TX" (required for US addresses)
- Canada: "ON", "BC", "QC"

**Note**: Required when country is "US"
    Example: VIC

  - `customerIdentity.residentialAddress.postCode` (string, required)
    Postal code, ZIP code, or postCode.
**Format varies by country**:
- Australia: 4 digits (e.g., "3121")
- USA: 5 digits or 5+4 format (e.g., "90210" or "90210-1234")
- UK: Alphanumeric (e.g., "SW1A 1AA")
- Canada: Alphanumeric (e.g., "K1A 0B1")
    Example: 3121

  - `customerIdentity.residentialAddress.country` (string, required)
    Two-letter ISO 3166-1 alpha-2 country code.
**Common Examples**:
- AU - Australia
- US - United States
- GB - United Kingdom
- CA - Canada
- NZ - New Zealand
- SG - Singapore

**Note**: The country must be supported by Banxa for the requested transaction type.
    Example: AU

  - `occupationIndustry` (string, required)
    The industry sector of the customer's occupation.
**Important**: The selected industry determines which specific occupations are valid. See the Occupation schema for the mapping table.
**Compliance Requirement**: Required for AML/KYC compliance to assess customer risk profile.
    Enum: "Consulting, IT, or business services", "Design, marketing or communication", "Travel, accommodation, or transport", "Entertainment, arts or photography", "Health, sports or personal care", "Food, beverages, or tobacco", "Retail, eCommerce, wholesale or manufacturing", "Dealers & Resellers", "Financial services, products, or holding companies", "Real estate or construction", "Education or learning", "Charity or not-for-profit", "Public or government services", "Utility services", "Unemployed/Retired", "In between jobs/looking for work", "Fulltime student"

  - `occupation` (string, required)
    Customer's occupation. Must be a valid occupation for the selected 'occupationIndustry'. When the selected combination is invalid a validation error will be thrown. Refer to the Occupation-Industry mapping table:
| occupationIndustry | occupation |
|  --- | --- |
| Consulting, IT, or business services | Architect |
| Consulting, IT, or business services | IT developer |
| Consulting, IT, or business services | IT hosting services |
| Consulting, IT, or business services | IT consulting/services - other |
| Consulting, IT, or business services | Scientific or technical consulting |
| Consulting, IT, or business services | Management consulting and coaching |
| Consulting, IT, or business services | Employment placement and recruitment services |
| Consulting, IT, or business services | Cleaning, repair and maintenance services |
| Consulting, IT, or business services | Financial (inc. tax, accounting, audit) |
| Consulting, IT, or business services | Lawyer / Legal services |
| Consulting, IT, or business services | Translation or language services |
| Consulting, IT, or business services | Company establishment/formation services |
| Consulting, IT, or business services | Freelance platform |
| Consulting, IT, or business services | Other consulting |
| Design, marketing or communication | Advertising and marketing |
| Design, marketing or communication | Designer |
| Design, marketing or communication | Interior design |
| Design, marketing or communication | Audio and video |
| Design, marketing or communication | Photography |
| Design, marketing or communication | Print and online media |
| Design, marketing or communication | Translation or language services |
| Design, marketing or communication | Telecommunications services |
| Travel, accommodation, or transport | Travel agent |
| Travel, accommodation, or transport | Tour operator |
| Travel, accommodation, or transport | Accommodation or hotelier |
| Travel, accommodation, or transport | Other travel or tour activities |
| Travel, accommodation, or transport | Passenger transport or rentals |
| Travel, accommodation, or transport | Freight transport |
| Travel, accommodation, or transport | Rideshare and transport share services |
| Travel, accommodation, or transport | Transport - other |
| Entertainment, arts or photography | Audio and video engineer |
| Entertainment, arts or photography | Events and entertainment organiser |
| Entertainment, arts or photography | Photographer |
| Entertainment, arts or photography | Books, magazines, blogs, news |
| Entertainment, arts or photography | Video gaming |
| Entertainment, arts or photography | Performing arts |
| Entertainment, arts or photography | Gambling, betting, and lotteries |
| Entertainment, arts or photography | Telecommunications services |
| Entertainment, arts or photography | Adult Entertainment |
| Health, sports or personal care | Beautician |
| Health, sports or personal care | Vitamins and dietary supplements |
| Health, sports or personal care | Fitness or sports services |
| Health, sports or personal care | Medical or veterinary services |
| Health, sports or personal care | Dental services |
| Health, sports or personal care | Medical equipment |
| Health, sports or personal care | Elderly or other care home |
| Health, sports or personal care | Nursing or other care services |
| Health, sports or personal care | Pharmaceuticals |
| Health, sports or personal care | Pharmacy |
| Food, beverages, or tobacco | Food manufacturing and retail |
| Food, beverages, or tobacco | Restaurants and catering |
| Food, beverages, or tobacco | Vitamins and dietary supplements |
| Food, beverages, or tobacco | Alcohol |
| Food, beverages, or tobacco | Soft drinks |
| Food, beverages, or tobacco | Tobacco |
| Retail, eCommerce, wholesale or manufacturing | Clothing and accessories |
| Retail, eCommerce, wholesale or manufacturing | Beauty products and services |
| Retail, eCommerce, wholesale or manufacturing | Home and garden |
| Retail, eCommerce, wholesale or manufacturing | Toys, games and musical instruments |
| Retail, eCommerce, wholesale or manufacturing | Electronics and electrical products |
| Retail, eCommerce, wholesale or manufacturing | Sports equipment (excl. weapons) |
| Retail, eCommerce, wholesale or manufacturing | Manufacturing |
| Retail, eCommerce, wholesale or manufacturing | Farming, seeds, plants |
| Retail, eCommerce, wholesale or manufacturing | Pets or pet supplies |
| Dealers & Resellers | Vehicle sales |
| Dealers & Resellers | Vehicle accessories, spare parts, manufacturing |
| Dealers & Resellers | Machinery and equipment |
| Dealers & Resellers | Firearms, weapons, and military goods/services |
| Dealers & Resellers | Arts - fine art sales, auctions or procurement |
| Dealers & Resellers | Arts - other arts and crafts products or services |
| Dealers & Resellers | Jewellery - fine jewellery, watches |
| Dealers & Resellers | Jewellery - fashion jewellery |
| Dealers & Resellers | Precious stones, diamonds, or metals |
| Dealers & Resellers | Chemicals |
| Dealers & Resellers | Legal highs and related accessories |
| Dealers & Resellers | Selling products on behalf of others (incl. auction, online marketplace) |
| Dealers & Resellers | Other retail or wholesale (not listed above) |
| Financial services, products, or holding companies | Financial Adviser (inc. tax, accounting, audit) |
| Financial services, products, or holding companies | Investment Manager |
| Financial services, products, or holding companies | Money service business operator |
| Financial services, products, or holding companies | Professional Trader |
| Financial services, products, or holding companies | Insurance Manager |
| Financial services, products, or holding companies | Crowdfunding and peer lending |
| Financial services, products, or holding companies | Other financial services |
| Real estate or construction | Real estate sale, purchase, and management |
| Real estate or construction | Construction |
| Real estate or construction | Real estate development |
| Education or learning | Online learning |
| Education or learning | Teaching and tutoring |
| Education or learning | Schools and universities |
| Charity or not-for-profit | Any charity related activity |
| Public or government services | Government Official |
| Public or government services | Politician |
| Public or government services | Other, not listed above |
| Utility services | Utility services and providers |
| Utility services | Cleaning, repair and maintenance services |
| Utility services | Telecommunications services |
| Utility services | Other, not listed above |
| Unemployed/Retired | Unemployed/Retired |
| In between jobs/looking for work | In between jobs/looking for work |
| Fulltime student | Fulltime student |
    Enum: "Architect", "IT developer", "IT hosting services", "IT consulting/services - other", "Scientific or technical consulting", "Management consulting and coaching", "Employment placement and recruitment services", "Cleaning, repair and maintenance services", "Financial (inc. tax, accounting, audit)", "Lawyer / Legal services", "Translation or language services", "Company establishment/formation services", "Freelance platform", "Other consulting", "Advertising and marketing", "Designer", "Interior design", "Audio and video", "Photography", "Print and online media", "Telecommunications services", "Travel agent", "Tour operator", "Accommodation or hotelier", "Other travel or tour activities", "Passenger transport or rentals", "Freight transport", "Rideshare and transport share services", "Transport - other", "Audio and video engineer", "Events and entertainment organiser", "Photographer", "Books, magazines, blogs, news", "Video gaming", "Performing arts", "Gambling, betting, and lotteries", "Adult Entertainment", "Beautician", "Vitamins and dietary supplements", "Fitness or sports services", "Medical or veterinary services", "Dental services", "Medical equipment", "Elderly or other care home", "Nursing or other care services", "Pharmaceuticals", "Pharmacy", "Food manufacturing and retail", "Restaurants and catering", "Alcohol", "Soft drinks", "Tobacco", "Clothing and accessories", "Beauty products and services", "Home and garden", "Toys, games and musical instruments", "Electronics and electrical products", "Sports equipment (excl. weapons)", "Manufacturing", "Farming, seeds, plants", "Pets or pet supplies", "Vehicle sales", "Vehicle accessories, spare parts, manufacturing", "Machinery and equipment", "Firearms, weapons, and military goods/services", "Arts - fine art sales, auctions or procurement", "Arts - other arts and crafts products or services", "Jewellery - fine jewellery, watches", "Jewellery - fashion jewellery", "Precious stones, diamonds, or metals", "Chemicals", "Legal highs and related accessories", "Selling products on behalf of others (incl. auction, online marketplace)", "Other retail or wholesale (not listed above)", "Financial Adviser (inc. tax, accounting, audit)", "Investment Manager", "Money service business operator", "Professional Trader", "Insurance Manager", "Crowdfunding and peer lending", "Other financial services", "Real estate sale, purchase, and management", "Construction", "Real estate development", "Online learning", "Teaching and tutoring", "Schools and universities", "Any charity related activity", "Government Official", "Politician", "Other, not listed above", "Utility services and providers", "Unemployed/Retired", "In between jobs/looking for work", "Fulltime student"

  - `sourceOfFunds` (string, required)
    The source from which the customer's funds are obtained.
**Compliance Requirement**: Required for AML compliance to verify the origin of funds.
**Common Sources**:
- Employment income (Salary)
- Business revenue (Business Income/Profits)
- Investment returns
- Savings and inheritance
    Enum: "Personal Savings", "Salary", "Business Income/Profits", "Pension", "Government Benefits", "Income from Cryptocurrency Trading", "Income from Investments (e.g. shares, bonds, investment funds)", "Income from sale of real estate or other property", "Income from renting/leasing", "Private loan from family members/ friends/others", "Loan from bank", "Inheritance", "Gift", "Other"

  - `purposeOfTransaction` (string, required)
    The intended purpose for the cryptocurrency transaction.
**Compliance Requirement**: Required for AML compliance to understand transaction intent.
**Note**: Currently only 'investment' is supported.
    Enum: "Investment", "Trading", "Payment for Online Purchase", "Payment for Services", "Gaming", "Charity", "Ransomware/Virus/Cyber Extortion Demands", "Other"

  - `identityDocuments` (array, required)
    Array of identity documents to verify the customer's identity.
**Minimum Requirements**:
- At least one government-issued photo ID (Passport, Driver's License, or National ID)
- Proof of Address (if required based on jurisdiction)
- Selfie (for liveness verification)

**Document Quality Requirements**:
- Clear, high-resolution images
- All text must be readable
- All four corners of the document visible
- No glare or shadows obscuring information
- Color images preferred
- Maximum file size: 10MB per image (before base64 encoding)

  - `identityDocuments.type` (string)
    The type of document provided.
    Enum: "DRIVING_LICENSE", "PASSPORT", "IDENTIFICATION", "PROOF_OF_ADDRESS", "SELFIE"

  - `identityDocuments.data` (object)
    Required when the document "type" is "PASSPORT", "DRIVING_LICENSE", or "IDENTIFICATION".

  - `identityDocuments.data.number` (string)
    Identifier number from the document.
    Example: 123456789

  - `identityDocuments.images` (array)
    One or more images of the document.

  - `identityDocuments.images.base64` (string, required)
    Base64-encoded file content. Maximum original file size before encoding is 10 MB.
    Example: iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P49/8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==

  - `identityDocuments.images.mimetype` (string, required)
    MIME type of the image, we support image/jpeg and image/png mimetypes
    Example: image/png

  - `identityDocuments.images.side` (string)
    The side of the identity document
    Enum: "FRONT", "BACK"

  - `identityDocuments.images.type` (string)
    Enum: "DRIVING_LICENSE", "IDENTIFICATION"

  - `identityDocuments.type` (string, required)
    Enum: "PASSPORT", "DRIVING_LICENSE", "IDENTIFICATION"

## Request examples:

  - `Complete identity submission with passport` (unknown)
    Example of a complete identity verification submission including passport, proof of address, and selfie

## Response 202:

  - `202` (unknown)
    The identity document sharing request has been accepted for processing, but the processing of the sent documents has not been finished yet.
**Next Steps**:
- Documents are being verified (typical time: 1-24 hours)
- You will receive a webhook notification when verification is complete
- Status will be either VERIFIED or REJECTED

## Response 202 fields (application/json):

  - `identityReference` (string, required)
    A unique customer identifier provided by the partner. This field is required and must be unique for each customer.
**Important**: You must consistently reuse the same identityReference for repeat interactions with the same customer, allowing Banxa to reliably recognize and associate their identity across multiple transactions.
**Format Requirements**:
- Only ASCII letters (a-z, A-Z), digits (0-9), and hyphens (-) are allowed
- Must be between 1 and 255 characters
- Case-sensitive

**Best Practices**:
- Use a consistent format across your system
- Consider using a prefix to identify your organization (e.g., 'partner-customer-123')
- Do not include personally identifiable information (PII) in the reference
- Store the mapping between your internal customer ID and this reference securely
    Example: c-13344

  - `status` (string, required)
    Current status of the identity verification.
**Status Meanings**:
- **PENDING**: Documents are being reviewed (typical review time: 1-24 hours)
- **VERIFIED**: Identity verified successfully, customer can transact
- **REJECTED**: Documents rejected, see rejectionReason for details
    Enum: "PENDING", "UNDER_REVIEW", "ACTION_REQUIRED", "VERIFIED", "REJECTED"

  - `rejectionReason` (object)
    Details about why the identity verification was rejected. Only present when status is REJECTED.

  - `rejectionReason.internalReason` (string)
    Internal code/reason for rejection. For logging and debugging purposes.
    Example: DOCUMENT_BLURRY

  - `rejectionReason.reason` (string)
    Human-readable rejection message that can be displayed to the customer.
**Common Reasons**:
- Document image is blurry or unclear
- Document is expired
- Information doesn't match provided details
- Document type not accepted
- Selfie doesn't match ID photo
    Example: The document image is blurry. Please re-submit a clear photo showing all details.

  - `customerIdentity` (object)

  - `customerIdentity.givenName` (string, required)
    Customer's given / first name.
    Example: Joe

  - `customerIdentity.surname` (string, required)
    Customer's surname / last name.
    Example: Bloggs

  - `customerIdentity.dob` (string, required)
    Customer's date of birth (e.g. "1985-01-31"). Required to format as ISO 8601 Date format : YYYY-MM-DD.
    Example: 1990-01-31

  - `customerIdentity.taxIdType` (string)
    The category of tax or government identifier supplied in `taxId`. The correct value depends on the customer's country and the identifier type accepted for that country.
| Value | Description |
|  --- | --- |
| `identity_card` | A government-issued identity card number used for identity or tax reporting in the customer's country. |
| `tax_id` | A tax identification number issued by a tax authority, such as a TFN, TIN, ITIN, or equivalent. |
| `national_number` | A national, citizen, resident, or social insurance number used to identify an individual in their country. |
| `ssn` | A Social Security Number, generally used for US individuals. |
    Enum: "identity_card", "tax_id", "national_number", "ssn"

  - `customerIdentity.taxId` (string)
    Tax identification number.
See [TIN validation](https://docs.banxa.com/products/native-api/docs/compliance/tin-validation).
    Example: 123-11-123

  - `customerIdentity.taxState` (string)
    Tax state or region if applicable.(associated with the taxId) Required format as two characters. Note; We do not accept any states where Banxa is not licensed.
    Example: IL

  - `customerIdentity.residentialAddress` (object, required)
    Customer's residential address. Required for identity verification and compliance purposes.
**Important**: This must be the customer's current residential address, not a PO Box or business address.

  - `customerIdentity.residentialAddress.addressLine` (string, required)
    Primary street address including street number and name.
**Examples**:
- "44 Gwynne Street"
- "123 Main Street, Apt 4B"
- "10 Downing Street"

**Requirements**:
- Must include street number and name
- Can include unit/apartment number
- Maximum 200 characters
    Example: 44 Gwynne Street

  - `customerIdentity.residentialAddress.suburb` (string, required)
    Suburb, city, or town name.
**Regional Variations**:
- Australia: Suburb (e.g., "Cremorne")
- USA: City (e.g., "New York")
- UK: Town/City (e.g., "London")
- Europe: City (e.g., "Paris")
    Example: Cremorne

  - `customerIdentity.residentialAddress.state` (string, required)
    State, province, or region code.
**Format**: Typically 2-3 character code
**Examples**:
- Australia: "VIC", "NSW", "QLD"
- USA: "CA", "NY", "TX" (required for US addresses)
- Canada: "ON", "BC", "QC"

**Note**: Required when country is "US"
    Example: VIC

  - `customerIdentity.residentialAddress.postCode` (string, required)
    Postal code, ZIP code, or postCode.
**Format varies by country**:
- Australia: 4 digits (e.g., "3121")
- USA: 5 digits or 5+4 format (e.g., "90210" or "90210-1234")
- UK: Alphanumeric (e.g., "SW1A 1AA")
- Canada: Alphanumeric (e.g., "K1A 0B1")
    Example: 3121

  - `customerIdentity.residentialAddress.country` (string, required)
    Two-letter ISO 3166-1 alpha-2 country code.
**Common Examples**:
- AU - Australia
- US - United States
- GB - United Kingdom
- CA - Canada
- NZ - New Zealand
- SG - Singapore

**Note**: The country must be supported by Banxa for the requested transaction type.
    Example: AU

  - `occupationIndustry` (string)
    Echo of the submitted occupation industry.
    Example: Consulting, IT, or business services

  - `occupation` (string)
    Echo of the submitted occupation.
    Example: IT developer

  - `purposeOfTransaction` (string)
    Submitted transaction purpose.
    Enum: "Investment", "Trading", "Payment for Online Purchase", "Payment for Services", "Gaming", "Charity", "Ransomware/Virus/Cyber Extortion Demands", "Other"

  - `createdAt` (string)
    UTC timestamp when the identity verification request was created.
**Format**: ISO 8601 date-time format
    Example: 2023-06-05T19:53:08.320Z

## Response 400:

  - `400` (unknown)
    Bad request due to invalid input.
**Common Causes**:
- Malformed JSON in request body
- Invalid data types
- Missing required fields
- Invalid request structure

## Response 400 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Bad Request

  - `code` (integer)
    HTTP status code
    Example: 400

  - `traceId` (string)
    Unique identifier for this error instance. Use this when contacting support.
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 401:

  - `401` (unknown)
    Authentication failed or missing credentials.
**Common Causes**:
- Missing Authorization header
- Invalid API key
- Expired or invalid HMAC signature
- Incorrect timestamp (must be within 5 minutes of server time)

## Response 401 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Unauthenticated.

  - `code` (integer)
    HTTP status code
    Example: 401

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 404:

  - `404` (unknown)
    The requested resource was not found.
**Common Causes**:
- Invalid ramp ID
- Invalid identity reference
- Resource has been deleted
- Incorrect endpoint URL

## Response 404 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Not Found

  - `code` (integer)
    Error code (may be HTTP status or custom code)
    Example: 500100

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 422:

  - `422` (unknown)
    Validation error - request is well-formed but contains invalid data.
**Common Causes**:
- Field validation failures
- Business rule violations
- Invalid field combinations
- Out of range values

## Response 422 fields (application/json):

  - `message` (string)
    Summary of validation errors
    Example: The given data was invalid.

  - `errors` (object)
    Map of field names to error messages.
**Format**: Each key is a field name, value is an array of error messages for that field.
    Example: {"email":["The email field is required."],"fiatAmount":["The fiat amount must be at least 10."]}

  - `code` (integer)
    HTTP status code
    Example: 422

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 429:

  - `429` (unknown)
    Rate limit exceeded.
**Rate Limits**:
- General API: 100 requests per minute
- Price endpoint: 60 requests per minute

**Action**: Wait for the duration specified in `Retry-After` header before retrying.

## Response 429 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Too Many Requests. Please try again later.

  - `code` (integer)
    HTTP status code
    Example: 429

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 429 headers (application/json):

  - `Retry-After` (integer)
    Number of seconds to wait before retrying.

**Important**: Always respect this header to avoid further rate limiting.
    Example: 60

## Response 202 examples:

  - `Verification pending` (unknown)