Errors

When a request is unsuccessful, the MGX Enterprise API returns a consistent error envelope with a numeric status, a stable machine-readable code, a human-readable message, and — for validation failures — a per-field errors array. Use the code for programmatic handling and the message for debugging.

You can tell whether a request succeeded from the HTTP status code. On failure, the body always has the same shape, so you can parse it the same way every time.

Status codes

Name
2xx
Description
Success. 200 for reads and updates, 201 for created resources.
Name
401
Description
Unauthorized — the token is missing, malformed, or expired.
Name
403
Description
Forbidden — the token lacks the required scope, is not a registered API client, or the team is not eligible (e.g. no payment method).
Name
404
Description
Not found — the resource does not exist or is not visible to your team.
Name
409
Description
Conflict — e.g. an active bid already exists, or an Idempotency-Key was reused with a different body.
Name
422
Description
Validation error — see the errors array for the offending fields.
Name
429
Description
Rate limited — you exceeded your client's per-minute ceiling. Honor the Retry-After header.

The error envelope

Every error response carries the same structure.

Name
error.status
Type
integer
Description
The HTTP status, repeated for convenience.
Name
error.code
Type
string
Description
A stable, machine-readable identifier you can branch on.
Name
error.message
Type
string
Description
A human-readable explanation.
Name
error.errors
Type
array
Description
Present on 422 only — per-field validation messages.

{
  "error": {
    "status": 422,
    "code": "validation_error",
    "message": "The given data was invalid.",
    "errors": [
      { "field": "quantity_mt", "message": "Quantity must be greater than 0." }
    ]
  }
}

Common error codes

Name
insufficient_scope
Description
The token is missing a scope the endpoint requires.
Name
not_api_client
Description
The token is valid but not from a registered Enterprise API client.
Name
no_team
Description
The token is not bound to a team — re-authorize with Login with MGX and select one.
Name
not_found
Description
No resource matched, or it is not visible to your team.
Name
active_bid_exists
Description
You already have an active bid on this listing.
Name
idempotency_key_reuse
Description
The Idempotency-Key was already used with a different request body.
Name
payment_required
Description
Your team needs a payment method or approved credit to bid.
Name
not_elevator
Description
Cash bids are only available to elevator accounts.