Errors

Standard error format

All error responses use a consistent JSON format:

{
  "detail": "Explanatory error message"
}

For 422 (validation errors), detail is an array:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "msisdn"],
      "msg": "Field required"
    }
  ]
}

HTTP error codes

Code	Situation	Example `detail`
`200`	Success (or idempotency hit)	—
`400`	Invalid parameter	`"Unknown operator: 'wave'. Accepted values: mtn, orange."`
`401`	Missing, unknown or revoked API key, or deactivated application	`"Invalid or missing API key."`
`403`	Valid API key without the scope required by the route	`"API key lacks scope 'deposits'."`
`404`	Transaction not found (or created by another application)	`"Transaction not found: 7c9e6679-..."`
`409`	`reference` already used by another application	`"Reference already used by another application."`
`422`	Validation error: missing field, wrong type, or MSISDN prefix contradicting `operator` (MTN: 67x/68x/650-654 · Orange: 69x/655-659)	Array of validation errors, or string detail for prefix mismatch
`503`	No provider available for this operator	`"No provider available for operator=mtn."`
`503`	Payment channel temporarily unavailable	`"Deposits are temporarily unavailable for this operator. Please retry later or use another payment method."`
`503`	Service paused by Winam (maintenance, direction or operator switched off)	`"The MTN network is temporarily disabled."`
`500`	Internal error	`"Internal error."`

Common errors

401 — Invalid or missing API key

Your X-API-Key header is missing or incorrect, the key was revoked, or your application was deactivated.

{ "detail": "Invalid or missing API key." }

Contact support@eins-innovativ.de to obtain or reset your API key.

403 — Missing scope

Your API key is valid but your application is not allowed to call this route (see Scopes).

{ "detail": "API key lacks scope 'withdrawals'." }

Contact Winam to have the scope added to your application.

409 — Reference used by another application

The reference you sent was already used by a different application. reference values are unique across the platform; re-sending one of your own references returns your original transaction instead.

{ "detail": "Reference already used by another application." }

Use references unique to your platform (for example prefixed with your platform name).

400 — Unknown operator

The operator field must be "mtn" or "orange".

{ "detail": "Unknown operator: 'wave'. Accepted values: mtn, orange." }

Use POST /api/v1/msisdn/detect to automatically detect the operator from the MSISDN.

422 — Validation error

A required field is missing or has an invalid type.

{
  "detail": [
    { "type": "missing", "loc": ["body", "reference"], "msg": "Field required" }
  ]
}

503 — No provider available

All providers for the requested operator are currently unavailable (feature flag disabled or degraded).

{ "detail": "No provider available for operator=mtn." }

Check GET /api/v1/CM/providers/status for real-time provider health.

503 — Channel temporarily unavailable

The payment channel for this operator cannot process the request right now. No transaction is created.

{ "detail": "Deposits are temporarily unavailable for this operator. Please retry later or use another payment method." }

Withdrawals return the same message starting with "Withdrawals are temporarily unavailable…". The detail is fixed and never describes the internal cause. Retry later or offer another payment method; GET /api/v1/CM/providers/status shows the provider as degraded or unavailable.

503 — Service paused

Winam has temporarily switched off transactions (maintenance), a direction or an operator.Possible detail values: "Service under maintenance — transactions temporarily suspended.", "Deposits are temporarily disabled.", "Withdrawals are temporarily disabled.", "The MTN network is temporarily disabled.", "The ORANGE network is temporarily disabled."

Get Started

Payments

Transactions

Providers

Security

Reference

Standard error format

HTTP error codes

Common errors