Errors

Every error has this body:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request.",
    "details": [
      {
        "origin": "string",
        "code": "too_small",
        "minimum": 1,
        "inclusive": true,
        "path": ["name"],
        "message": "Too small: expected string to have >=1 characters"
      }
    ]
  }
}

details comes in two shapes. On a body, query or :id VALIDATION_ERROR, it is the list of validation problems, one per field. In the cases of the table below, it is an object that says what clashed. Other errors have no details. The text of each message may change: use code and details.

ExamplesCopy Anchor Link

409 CONFLICT has several causes (listed in the table above). Tell them apart by details; the reused Idempotency-Key is the only one without it.

Repeated externalId, with details.field:

{
  "error": {
    "code": "CONFLICT",
    "message": "A seller with this externalId already exists.",
    "details": { "field": "externalId" }
  }
}

Seller with active connections, on DELETE /v1/sellers/<id>:

{
  "error": {
    "code": "CONFLICT",
    "message": "Seller with active connections cannot be removed. Disconnect them first.",
    "details": { "reason": "active_connections" }
  }
}

Link session that is no longer pending, on DELETE /v1/link-sessions/<id>:

{
  "error": {
    "code": "CONFLICT",
    "message": "Only a pending link session can be revoked.",
    "details": { "status": "completed" }
  }
}

400 for a missing Seller-Id, on GET /v1/connections:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Seller-Id header is required.",
    "details": { "header": "Seller-Id" }
  }
}

Idempotency-Key reused with a different body, no details (see Idempotency and limits):

{
  "error": {
    "code": "CONFLICT",
    "message": "Idempotency-Key already used with a different body."
  }
}

422 CAPABILITY_UNSUPPORTED, when publishing a listing on a Connection whose marketplace does not publish. 403 CAPABILITY_NOT_GRANTED has the same details. In an inventory batch the error is not in the response: that Connection's item fails in the job, with the code in its message.

{
  "error": {
    "code": "CAPABILITY_UNSUPPORTED",
    "message": "Marketplace mercadolivre does not support listings.publish.",
    "details": {
      "marketplace": "mercadolivre",
      "capability": "listings.publish"
    }
  }
}

402 PAYMENT_REQUIRED (no subscription in good standing; it does not count toward the rate limit):

{
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Subscription required. Add a payment method in the dashboard."
  }
}

429 RATE_LIMITED comes with the Retry-After header (seconds):

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again after the time given in Retry-After."
  }
}

500 INTERNAL_ERROR:

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal error."
  }
}

503 MARKETPLACE_UNAVAILABLE, on the Connection discovery and catalog routes, which read the marketplace right away. details.reason tells a wait from an outage:

{
  "error": {
    "code": "MARKETPLACE_UNAVAILABLE",
    "message": "The marketplace is limiting requests. Try again.",
    "details": { "reason": "marketplace_rate_limited" }
  }
}

If the marketplace ended the seller's access in the middle of the call, the answer is not 503: it is 409 CONFLICT with { "reason": "connection_inactive" }, the same as any route of a Connection that is not active. Ask the seller to connect again.

Handle errors by code, not by message: the message may change, the code won't. The message is in English and is meant for logs and debugging.

Each endpoint page shows the errors it can return, with an example body for each status. For example: Create a seller.