Status and Common Errors

Plumma® CONNECT API — Response Handling and Diagnostics

The Plumma® CONNECT API uses two distinct layers of error signalling:

• HTTP-level errors are returned by the security filter before the request reaches the API logic. These occur when the API key is invalid, expired, revoked, or when access limits are exceeded. In these cases, the response body is not a PlmResponse JSON object, but a plain HTTP error or a small JSON error payload.
• Response-level status is present inside the PlmResponse JSON body for all requests that pass authentication successfully. Every such response includes a status (numeric) and a status_message (string) describing the outcome of the query against the network operators. As of the latest release, both fields are produced by the Merge step, which combines the answers of every supplier consulted for the request into a single result.

HTTP-Level Errors (Authentication & Access Layer)

These errors are returned by the API security filter and never produce a PlmResponse body. This layer is unchanged.

Response-Level Status (PlmResponse Body)

For all authenticated requests, the PlmResponse body includes a top-level status field and a status_message string. Both are (re)computed as the final step of the request, after the Merge engine has collected and combined the answers returned by every routed supplier.

status

status is still one of the five overall outcome codes below. The logic used to pick the code is now centralized and evaluated in this fixed order:

status_message

status_message is no longer a single static sentence per status code. It is now assembled dynamically by the Merge step and can contain up to four parts, appended in this order:

1. Base outcome text, chosen from:
   • No commands available in country [] — when no command could be routed at all (status = 2).
   • Partial reply merged from multiple operators — when more than one supplier answered.
   • Response from one supplier — when exactly one supplier answered.
   • Unknown error — fallback when the outcome could not be determined.
2. Skipped commands note (only if one or more requested commands had no coverage for the resolved country):
   - Commands [, , ...] not available in []
3. Demo/sandbox note (only when the call was served by the sandbox engine, i.e. an SandBox demo user key rather than a production Production User key : - This response is for demo purpose only
4. Per-command outcome block, appended in square brackets and containing:
   • [cmd_enc=] — a single number that packs the outcome of every command requested into one value (see “Decoding cmd_enc” below), followed by
   • [: : | : : | ...] — one human-readable entry per routed command, naming the supplier that served it and either its own status message or a generic OK / failed.

Example — two commands requested, one served by MNO (A) and one that fell back to a second MNO (B) for the country, one command not covered:

Partial reply merged from multiple operators - Commands [scam_check] not available in [IT] [cmd_enc=17] [current_carrier: MNO (A) : OK | kyc_match: MON (B) : no data]

This is a static per-status sentences documented earlier and gives you, in a single field, both the aggregate outcome and the outcome of each individual command.

Per-Command Outcome

Where the previous version of this document listed a fixed "error" field on each failed command (not authorized, not configured, timeout, no data), the merged response now exposes per-command outcomes in two complementary ways inside status_message.

1. Human-readable breakdown

The bracketed list at the end of status_message (e.g. [current_carrier: MNO (A): OK | kyc_match: MNO (B): no data]) gives one entry per command that was actually routed, in the format:

: : 

The portion is sourced directly from the supplier's own response where available (for example a specific reason such as no data or a timeout description), or falls back to a generic OK / failed if the supplier did not provide one. Commands that were never routed at all (no coverage for the country) do not appear here. They are listed separately in the "Commands ... not available in ..." note described above.

2. Decoding cmd_enc (DEBUG ONLY)

cmd_enc is a single numeric value that encodes the outcome of every possible command in 2 bits each, packed into one number. Each command occupies the bit position ordinal × 2, where ordinal is the command's position in the list below (0-indexed):

Each 2-bit slot can hold one of three values:

This encoding is intended for programmatic consumers that want a compact machine-readable outcome per command, in addition to the human-readable breakdown described above.