Skip to content

Errors

This page describes the error response format used across the Depop Selling API, lists the error codes you may encounter, and explains how to resolve the most common failures.

Error response format

When a request fails, the API returns a JSON body with this structure:

{
  "id": "a210923f-c1f3-4d84-a2bd-7f18c68553e2",
  "errors": [
    {
      "code": "too_many_pictures",
      "message": "Failed to create or update product (sku: ABC-123) because too many pictures were provided. The maximum is 8 pictures."
    }
  ]
}
  • id is a unique identifier for this error response. Always log it — including it when you contact us lets us trace the exact request in our systems.
  • errors is a list of error items, each with a code and a human-readable message.

Note

The OAuth token endpoints return a different error format. See Authentication for details on OAuth error responses.

HTTP status codes

Status Meaning Should you retry?
400 Bad Request The request body or parameters could not be parsed. Check the request against the API Reference. No — fix the request first.
403 Forbidden The token is valid but is missing a required OAuth scope. No — request the missing scope during authorisation.
404 Not Found The resource (product, order, parcel) does not exist, or the URL path is wrong. No, unless you have just created the resource (see product_not_found below).
409 Conflict The request conflicts with the current state of the resource (for example, deleting a product with active offers). No — resolve the conflict first.
414 URI Too Long The request URL is too long or malformed. Check query parameter encoding and length. No — fix the URL first.
422 Unprocessable Entity The request is well-formed but fails validation. The error message explains the rule that was violated. No — fix the data first.
429 Too Many Requests You have exceeded a rate limit. See Rate limits. Yes — back off and retry with reduced request rate.
500 Internal Server Error Something went wrong on our side. Yes — retry with exponential backoff. If persistent, contact us with the error id.
504 Gateway Timeout The request timed out on our side. The operation may or may not have completed. Yes — but verify first whether the operation succeeded (for example, fetch the product) to avoid duplicates.

Error codes

Authentication and access

Code Status Meaning What to do
unauthorized 401 The access token is or API key missing, invalid or expired. Verify your tocken is correct. If using OAuth, refresh the token using your refresh token. Make sure only one refresh request is in flight at a time — see Using OAuth refresh tokens.
insufficient_scope 403 The token does not include a required OAuth scope. The message names the scope(s) needed, e.g. Required scope: offers_write. Request the missing scope when the seller authorises your app, and have the seller re-authorise.
partner_access_denied 401 API access for your partner account is currently disabled. Contact us to re-enable access.

Products and listings

Code Status Meaning What to do
product_not_found 404 No product matches the given SKU, product ID or slug for this seller. Check the identifier. A newly created listing can take a short time to become retrievable — if you fetch a product immediately after creating it, retry after a brief delay rather than treating the first 404 as permanent.
product_not_on_sale 422 The operation requires a product that is currently on sale, but this one is not (it may be sold or removed). Fetch the product to check its state before retrying.
product_has_active_offers 409 You attempted to delete a product that has active offers, with fail_if_active_offers set. Wait for offers to expire (offers last 24 hours), or delete without the flag if you accept cancelling active offers.
product_has_been_banned 422 The product has been banned on Depop, so it cannot be modified. Contact us with the SKU or product ID from the message if you believe this is a mistake.
too_many_pictures 422 More than 8 pictures were provided. Send at most 8 pictures per listing.
ingest_picture_error 422 We could not download or process one of the picture URLs. The message includes the failing URL. Check the URL is publicly accessible and serves a valid image. Picture URLs must be live at the time of the request — links to images that have since been deleted (including expired Depop image links) will fail.
invalid_description 422 The description failed validation. Use a maximum of 5 hashtags, and only tag the brand the item belongs to.
invalid_brand 422 The brand ID is not valid. Check the brand against the taxonomy.
invalid_size 422 The size is not valid for the selected category. Check the size and size set against the taxonomy for the chosen category.
invalid_department 422 The category could not be resolved — usually a missing or invalid department (gender). This commonly happens when relisting older products that pre-date the current taxonomy. Provide a valid department, and remap legacy category IDs to the current product type and department. See taxonomy.
manual_shipping_not_allowed 422 This seller is not permitted to list with manual shipping. Manual shipping is not available to most US sellers. Use Depop Shipping for this seller instead. See Managing shipping for how to determine which shipping methods a seller can use.
unsupported_country 422 The seller's country is not supported for this operation. The message lists supported countries. Do not retry for this seller.

Orders and offers

Code Status Meaning What to do
purchase_id_not_found 404 No order matches the given purchase ID for this seller. Check the purchase ID.
parcel_id_not_found 404 No parcel matches the given parcel ID. Check the parcel ID from the order details.
offer-specific codes 422 Offer submissions can fail with additional codes passed through from our offers system. The message explains the reason. See Managing offers and the validation rules below.

Validation

Code Status Meaning What to do
validation 422 The request failed a business validation rule. The message states the rule, e.g. Requested quantity (0) must not be negative. Read the message — it is specific. Common cases are listed in Common validation rules below.

Generic and internal errors

Code Status Meaning What to do
generic_error varies A catch-all code. When the status is 4xx, the message usually carries a specific reason from an internal system (for example Address does not belong to this user) — treat the message as the source of truth. When the status is 5xx, the message is An error has occurred. Please try again later. For 4xx: fix the request based on the message. For 5xx: retry with backoff, then contact us with the error id.
unexpected_response varies An internal service returned a response we did not expect. The message may be empty. Retry with backoff. If persistent, contact us with the error id.
depop_json_deserialization 500 An internal response could not be processed. Retry with backoff. If persistent, contact us with the error id.
missing_address_configuration, missing_partner_configuration 500 Your partner or address configuration is incomplete on our side. Contact us — this needs to be fixed by Depop.

Match on code, not message

Error message text is intended for developers and may be reworded over time. Build your error handling on the code and HTTP status, and use the message for logging and diagnosis. When showing errors to your users, map codes to your own user-friendly copy rather than displaying our messages directly.

Common validation rules

These are the most frequent validation failures. The rule is always stated in the error message.

Listing:

  • Quantity must be at least 1 when creating a listing. Use the mark-as-sold endpoint to sell out a listing, or set quantity to 0 via patch. See Restocking.
  • Shipping — either Depop Shipping or a national shipping cost must be provided on every listing. See Managing shipping.
  • Size cannot be changed on an existing product — updates that change size_id fail with Existing product sizeId can not be changed. To correct a size, delete the listing and create a new one. A non-variant product also cannot be converted to a variant (multi-size) product by update.
  • SKUs must be unique per seller — creating a listing with a SKU that already exists (including on sold or deleted products) fails with a duplicate-SKU error.
  • Seller address — the address used for a listing must belong to the authenticated seller, otherwise the request fails with Address does not belong to this user. Never hardcode address IDs; fetch the seller's addresses first.

Offers and discounts:

  • auto_send_offer_price must be lower than the product price.
  • auto_negotiate_offer_price must not exceed the product price minus the minimum percentage off.
  • discount_price must be lower than the product price.
  • A manually submitted offer must be in the product's currency and at least the minimum percentage lower than the product price.
  • If a product has multiple sizes, a size ID is required when submitting an offer; if it has a single size, a size ID must not be provided.

Refunds:

  • A refund must include an item amount and/or a shipping amount, both positive.
  • The items refund amount cannot exceed the product price, and the shipping refund amount cannot exceed the shipping price.

Request limits:

Field / parameter Limit
Pictures per listing 8 maximum
Hashtags per description 5 maximum (only tag the item's own brand)
SKU length 50 characters maximum
Products list page size (limit) 100 maximum
Orders list page size (limit) 200 maximum

Handling errors in your integration

  • Retry 5xx and 504 with exponential backoff and jitter. Do not retry 4xx responses (except 429) — the request will fail again until it is fixed.
  • Verify before re-creating. After a timeout on a create operation, check whether the resource was actually created before retrying, to avoid duplicate listings.
  • Handle 429 by slowing down, not hammering. Use a throttled queue and spread scheduled jobs (for example bulk relisting) over time instead of firing them in bursts at fixed intervals. See Rate limits.
  • Treat unknown codes gracefully. New error codes may be added over time (announced in the Changelog). Fall back to the HTTP status for behaviour and log the full response.
  • Log the error id together with the endpoint, timestamp and your request payload.

Getting help

If you cannot resolve an error, reach out through your partner Slack channel and include:

  • the error id from the response body,
  • the endpoint and HTTP method,
  • the timestamp (with timezone) of the request,
  • the full error response, and the request payload with any personal data removed.

This lets us trace the request straight away instead of asking follow-up questions.