Developers
API errors
Every error comes as application/problem+json with a stable type. Branch on the type, not on the text: here is what each one means and what to do.
Can’t find the answer, or the error keeps coming back? Write to us and quote the X-Request-Id from the response so we can find the request. Contact us
Status 401
- api_token_expired
API token has expired
The expiry date of the token has passed.
- api_token_invalid
API token is not valid
The token has a wrong format, its checksum does not match or there is no such token.
- api_token_missing
API token required
The request has no Authorization: Bearer header. A token in the query string is not accepted.
- api_token_revoked
API token has been revoked
The token was revoked, the app was deleted, its service member was turned off or the store was closed.
Status 403
- capability_disabled
Resource not available to this store
The resource depends on a store capability this store does not have; capability names it. Tax periods, for example, exist only for Argentine stores.
- forbidden
Forbidden
An access rule of the store denied the action beyond the scopes, such as a location the app does not work with.
- insufficient_scope
Scope is missing
The app lacks the scope the endpoint needs; required_scope names it, as does the WWW-Authenticate header. An endpoint that accepts any of several scopes lists them in accepted_scopes — any one is enough.
- integration_api_not_in_plan
Integration API is not in the plan
The plan of the store does not include the Integration API.
- ip_not_allowed
Address is not allowed
The app accepts requests only from listed IP addresses, and this request came from another one.
Status 404
- not_found
Not found
The record does not exist or belongs to another store; an unknown path gets the same response.
Status 405
- method_not_allowed
Method not allowed
The path exists but does not accept this HTTP method.
Status 409
- address_book_full
The customer's address book is full
The address book of the customer reached the limit of the store; limit is the ceiling.
- bulk_operation_finished
The operation has already finished
The operation has already finished and cannot be cancelled; operation_status is its status.
- bulk_operation_queue_full
The app operation queue is full
The app already has as many unfinished bulk operations as allowed; limit is the ceiling.
- bulk_operation_result_unavailable
There is no result file
The result of a file operation appears in full only when it is completed, and this operation is still running, failed or was cancelled; operation_status is its status.
- consent_required
Consent to the consequences is required
The write would change other data of the store: consent_kind names the kind of consequence, consequences counts what will change, consent_token is the fingerprint of what was shown.
- customer_contact_in_use
The contact already belongs to a store customer
The phone or email of a new customer already belongs to a customer of the store; field and existing_customer_id name them.
- draft_order_closed
The draft order is closed
The draft was placed or cancelled and can no longer be changed or placed; current gives its status and the order.
- external_id_archived
The record with this external ID is archived
The external ID belongs to an archived record of the store; external_id names it.
- external_id_in_use
The external ID is taken
The external ID is already used by another live record of this app; external_id names it.
- fiscal_document_annul_refused
The invoice can't be annulled
The invoice cannot be annulled. code is the reason: not_an_invoice — the document is not an invoice; not_issued — the invoice is not issued: a rejected one is reissued, a pending one is cancelled with the order; provider_disabled — the fiscal module of the store is off; already_voided — the invoice is already annulled or its note waits to be issued; nothing_to_void — the sale was refunded in full and the credit notes cleared the invoice. current.status is the document status, current.annulling_document_id is the current annulling note for already_voided.
- fiscal_document_dismiss_refused
The document can't be dismissed
The document cannot be dismissed. code is the reason: not_awaiting_decision — the document does not wait for a human decision: rejected documents and CAEA documents whose reporting ARCA refuses are dismissed; already_resolved — the document is already dismissed. current.status is the document status now.
- fiscal_document_pdf_unavailable
Document has no file
The document has no file: it is not issued, or the provider kept neither a file nor the data to build one; current.status is the document status.
- fiscal_document_reissue_refused
The document can't be reissued
The document cannot be reissued. code is the reason: not_reissuable — the document has neither failed nor been rejected: it waits to be issued or is issued; advance_applied — a booking advance was applied to the check, and the check invoice already documents it; nothing_to_issue — the order was refunded in full. current.status is the document status now.
- idempotency_key_in_use
A request with this key is in progress
A request with the same Idempotency-Key is still running.
- in_use_conflict
Record in use
The record cannot be deleted: other data of the store still refers to it.
- invoice_issue_refused
The order invoice can't be issued now
The order invoice cannot be issued now. code is the reason: channel_not_first_party — the sales channel issues the document; entity_exempt — the legal entity of the order issues no documents; issued_externally — an external POS issues the document; provider_disabled — the fiscal module of the store is off; not_covered — the sale is not paid yet; advance_applied — a booking advance was applied to the check, and the check invoice documents it; invoice_exists — the invoice already exists or waits to be issued; invoice_rejected — the tax authority rejected the invoice; nothing_to_issue — the order was refunded in full; bill_required — the table has several bills, a bill invoice is issued by the POS or the dashboard. current.invoice_id is the current invoice of the order for invoice_exists and invoice_rejected.
- money_transaction_locked
The transaction cannot be changed by hand
The ledger line cannot be edited or deleted by hand: it has a source document (then only the category, the counterparty and the description change), it is a service line of the ledger (opening balance, exchange difference, reflection of a group store) or it is a transfer leg. detail names the reason, current.origin is the origin of the line, current.transfer_id is the transfer.
- order_cancel_refused
The order cannot be cancelled
The order cannot be cancelled now: its status does not allow it, a credit note cannot be issued, cash is refunded only by a register with an open shift, or a paid subscription is running.
- order_transition_refused
The order cannot move to this status
The store does not allow this status change of the order: the transition rules, pickup without a courier, delivery without a courier or an unpaid balance before completion. detail names the reason, current shows the status now.
- payment_not_confirmable
The payment cannot be confirmed
The payment no longer waits for money or is closed by its provider, not by hand; current shows its status.
- plan_limit_reached
The plan limit is reached
The plan of the store does not allow more records of this kind; limit is the ceiling.
- purchase_order_refused
The purchase order does not accept this command
The purchase order does not accept the command in its current state: only drafts and placed orders change, only drafts are deleted, placed orders are cancelled, received ones are closed, and an order is placed only with an active supplier and location. detail names the reason, current.status holds the order status now.
- record_limit_reached
The record limit is reached
The store has reached the limit of records of this kind; limit is the ceiling. It does not depend on the plan.
- refund_not_confirmable
The refund does not await a payout confirmation
The refund has no manual payout waiting for confirmation: the money was returned by a provider, a register or the balance.
- refund_refused
The order cannot be refunded
The state of the order does not allow the refund: cancelled, no money received, cash already handed over to the register, the card of the sale spent, or a deposit holds a booking. detail names the reason.
- shipment_in_progress
A shipment issue is already under way
A shipment issue for the order is already queued or running, or the shipment is being cancelled.
- shipment_label_unavailable
No shipping label
The order has no shipment, the carrier has not provided the label yet, or its file is unavailable.
- shipment_outcome_unknown
The previous issue has an unknown outcome
The connection to the carrier dropped after the previous issue request, and it is unknown whether the shipment was created.
- shipment_refused
The shipment cannot be issued now
The shipment cannot be issued now: the order's delivery method has no integrated carrier, the order no longer ships or it awaits payment of its bill. code is the reason (no_carrier, not_shippable, awaits_bill_payment), current is the order status now.
- shipment_tracking_refused
The tracking number can't be written manually
The order's tracking number can't be written or removed manually. code is the reason: carrier_integrated — an integrated carrier issues the number, the shipment is issued with POST /v1/orders/{order}/shipment; manual_tracking_unsupported — the order's delivery method doesn't ship with a delivery service; order_closed — the order is cancelled or refunded. current is the order status now.
- stock_held_by_write_offs
Stock is held by write-offs awaiting approval
Setting the stock lower would take quantity held by write-offs waiting for approval in the store.
- stock_on_hand_changed
On-hand quantity changed
The on-hand stock differs from expected_on_hand: it changed after you read it. current.on_hand shows the stock now.
- supplier_bill_payment_locked
The bill payment cannot be cancelled directly
The supplier bill payment cannot be cancelled directly: an offset, a credit note, a purchase order advance and a ledger expense are removed by their own document, and a withholding made with the payment in a closed tax period keeps the payment too. detail names the reason, current.kind holds the payment kind.
- supplier_bill_refused
The supplier bill does not accept this command
The supplier bill does not accept the command in its current state: only a draft can be changed or deleted, a posted bill is not changed, a voided one is not posted, and notes already posted against a draft prevent deleting it. Only a posted bill is approved, approval cannot be revoked after the first payment, and only a posted and approved bill is paid. detail names the reason, current.status holds the bill status now.
- tax_withholding_certificate_unavailable
Record has no certificate
The store issues a certificate only for tax it withheld itself (direction practiced), from its legal entity: tax withheld from the store is backed by the agent paper. current.direction is the record direction, current.legal_entity_id its legal entity.
- unique_conflict
Duplicate value
A concurrent request took a unique value, such as an address or an SKU, between the check and the write.
- upload_offset_mismatch
The chunk does not start where expected
The offset of the chunk differs from what the upload has received; received is the right offset.
- webhook_endpoint_limit_reached
The app has the maximum number of webhook endpoints
The app already has as many webhook endpoints as allowed; limit is the ceiling.
Status 410
- cursor_expired
Sync cursor expired
The sync cursor is older than the retention period of deletions or was issued before the database of the store was restored.
Status 412
- precondition_failed
The record has changed
The version in If-Match is not current: the record changed after you read it. For If-None-Match: * — the record already exists.
Status 416
- range_not_satisfiable
The range starts beyond the result
The range starts beyond the written result; Content-Range gives its length.
Status 422
- idempotency_key_required
Idempotency key is required
The method runs only with the Idempotency-Key header: a duplicate with the tax authority cannot be undone.
- idempotency_key_reused
Idempotency key is already used
The key was already used by another request: a different method, path or body.
- invalid_idempotency_key
Idempotency key is invalid
The Idempotency-Key header could not be read: a key is 1 to 255 visible ASCII characters, sent as a token or a quoted string.
- last_variant_of_product
Last variant of the product
A product cannot stay without variants, so its last variant cannot be archived.
- money_out_of_range
Amount out of range
A price, quantity or unit gives an amount too large to calculate exactly.
- validation_error
Invalid request
A field or parameter is invalid or unknown; errors lists the messages by field.
Status 428
- precondition_required
If-Match is required
Changing a versioned record needs If-Match with its ETag; * is not a version.
Status 429
- too_many_requests
Too many requests
The rate limit is exhausted; policy names the bucket — app, store or rejected — and Retry-After says how long to wait. rejected means too many requests from your address were rejected on entry: a missing, invalid, revoked or expired token, an address that is not allowed, a plan without the API.
Status 500
- server_error
Server error
An unexpected failure on our side. The request did not complete.
Status 503
- carrier_unavailable
Carrier unavailable
The carrier did not respond to a request the store makes to it on your behalf (the shipping label at Mercado Envíos).
- store_frozen
Store frozen
The store is frozen for an unpaid subscription.
- transient_conflict
Temporary conflict
A concurrent change rolled the request back as a whole; nothing was written.
Status depends on the request
- http_error
HTTP error
An HTTP error without its own type, such as 503 during maintenance.