Loading the search index…

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

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.