Error Codes

The CoinMENA Partner API uses two layers of error information to help you identify and handle failures precisely:

• HTTP status codes indicate the broad category of failure (authentication, validation, not found, etc.)
• Application error codes (code field) explain the exact business or validation reason for the failure

Always handle errors using the application code field — it is stable and intended for programmatic use. The msg field is human-readable and may change over time. Multiple errors can share the same HTTP status code but have different application codes — always rely on code for precise handling.

Error Response Structure

Every error response returns a JSON object with the following fields:

{
  "code": 2008,
  "msg": "Invalid client ID",
  "msg_detail": null
}

How to Interpret an Error Response

When you receive an error, follow this order:

1. Check the HTTP status — determines the broad failure category
2. Check code — identifies the exact error reason
3. Check msg — provides a human-readable description for logging or display
4. Inspect msg_detail — if present, contains field-level validation errors or trading context

📘

Common debugging flow

If you receive an unexpected error:

1. Check the HTTP status first
2. Review the application code against this reference
3. Use msg_detail to identify which field or value caused a validation failure
4. Compare your request payload with the documented trigger for that error code

Decimal Fields and Scientific Notation

Decimal fields are returned as JSON strings and may use scientific notation when the value is very small or zero (e.g. "0E-8", "1e-8"). Always parse decimal fields using a decimal-aware type.

⚠️

Important

Do not parse decimal fields as JavaScript number or Python float — these types lose precision with financial values. Use Decimal in Python or a library like decimal.js in JavaScript.

HTTP Status Codes

401 — Unauthorized

A 401 response can be returned for multiple reasons — invalid signature, expired timestamp, missing headers, or IP not whitelisted. All triggers return the same response body, so you cannot distinguish the cause from the response alone.

{
  "code": 401,
  "msg": "Unauthorized",
  "msg_detail": null
}

📘

Debugging 401 errors

Since all 401 triggers look identical, work through the Authentication guide's troubleshooting checklist systematically. See the Authentication guide for the full checklist, and the IP Whitelisting guide if IP issues are suspected.

422 — Validation Error

Returned when the request body or parameters fail schema validation. The msg_detail field contains an array of field-level errors.

{
  "code": 422,
  "msg": "Validation Error",
  "msg_detail": [
    {
      "type": "email_parsing",
      "loc": ["body", "email"],
      "msg": "Input should be a valid email"
    }
  ]
}

Each object in msg_detail contains:

Common 422 Triggers

Application Error Codes

Client Status Errors

Errors related to existing clients — identity, verification status, and activity state.

Client Onboarding Errors

Returned by POST /v1/partner/clients (create) and PUT /v1/partner/clients/{id} (update) when client payload validation fails.

📘

2024 and 2026 on update

place_of_birth_id and partner_client_id are immutable after client creation — they cannot be modified via PUT /v1/partner/clients/{id}. Errors 2024 and 2026 can only occur on client creation.

Asset Errors

📘

GET /v1/partner/balances/{asset_id} — two possible 400 errors

This endpoint can return either 2012 (invalid asset) or 2008 (invalid client) when a partner_client_id query parameter is supplied and doesn't match. Check the code field to determine which.

Order and Funds Errors

📘

3005 on quotes

When returned on POST /v1/partner/quotes, the response includes a quote object in msg_detail with the calculated price and amounts. You can use this to show the client the current market rate even when the trade cannot be executed.

{
  "code": 3005,
  "msg": "Insufficient funds",
  "msg_detail": {
    "quote": {
      "market_price": "74100.4093",
      "base_amount": "0.13000000",
      "quote_amount": "9633.15",
      "fee_amount": "0.09",
      "vat_percentage": null,
      "vat_amount": "0.00",
      "lifetime": 15,
      "token": null
    }
  }
}

Trading Errors

Trading errors 4000, 4001, 4003, 4004 apply to POST /v1/partner/quotes. Error 4008 applies to POST /v1/partner/quotes/execute.

📘

Trading errors and msg_detail

Errors 4000, 4001, 4003, and 4004 return a quote object in msg_detail even on failure. For 4003 and 4004, a limit field is also returned showing the applicable minimum or maximum volume. Use this to show the user the current market price and explain why their trade was rejected.

{
  "code": 4004,
  "msg": "Amount is below the minimum allowed",
  "msg_detail": {
    "limit": "0.00020000",
    "quote": {
      "market_price": "74815.8482",
      "base_amount": "0.00000200",
      "quote_amount": "0.15",
      "fee_amount": "0.00",
      "vat_percentage": null,
      "vat_amount": "0.00",
      "lifetime": 15,
      "token": null
    }
  }
}

Not Found Errors

{
  "code": 404,
  "msg": "Not Found",
  "msg_detail": null
}

Recommended Error Handling

📘

Integration best practices

• Always use the application code for programmatic error handling — not msg
• Log both the HTTP status and the application code for every error
• Surface user-friendly messages in your app rather than raw API error messages
• Never retry 422, 409, or client onboarding 400 errors without modifying the request first