Fout-envelop
{
"error": {
"code": "asset_not_found",
"message": "No asset with id 42 for this shop",
"status": 404,
"request_id": "req_..."
}
}
Vermeld de request id wanneer u contact opneemt met de ondersteuning.
Veelvoorkomende foutcodes
| HTTP | Code | Betekenis |
|---|---|---|
| 400 | invalid_request | Ongeldige JSON of ontbrekend veld. Bij POST /assets/uploads/{uploadId}/complete is dit ook het antwoord op een ongeldige parts-lijst: parts mag niet leeg zijn, elk PartNumber moet een geheel getal van 1 tot 10.000 zijn, zonder duplicaten, en elke ETag een niet-lege string (in willekeurige volgorde; de lijst wordt gesorteerd op PartNumber). Een ongeldige lijst, of een lijst die de opslag weigert, laat de upload open: stuur opnieuw de deelnummers en ETags die de PUT-verzoeken voor de delen hebben teruggegeven. Een file_id buiten het bereik van een 32-bits geheel getal wordt op dezelfde manier geweigerd, voordat er iets wordt geschreven. Bij een gepagineerde lijst wordt ook een search-waarde die een NUL-teken (%00) bevat met deze code geweigerd. |
| 400 | idempotency_key_required | Schrijfverzoek zonder Idempotency-Key. |
| 401 | unauthorized | Ontbrekend, ongeldig, onbekend of ingetrokken token. |
| 402 | plan_required | De winkel heeft het Free-abonnement. De externe API vereist een betaald abonnement. Een voorbestelling aanmaken, de datum ervan verplaatsen (PATCH /preorders/{id} met release_at) of er een aan een koppeling toevoegen vereist ook een abonnement dat voorbestellingen omvat. Bij een productupdatemelding betekent het ook dat het abonnement van de winkel niet actief is, en een campagne die om een van beide redenen is gestopt nadat ze in de wachtrij stond, meldt error: plan_required bij GET /notifications/{id}. |
| 403 | forbidden | De externe API is uitgeschakeld (de globale noodschakelaar), de API-sleutel mist een scope die het verzoek nodig heeft, of Alva heeft op de routes voor productupdatemeldingen die meldingen als noodrem uitgeschakeld. Neem contact met ons op als een sleutel met de juiste scopes dit antwoord krijgt. Bij POST /share-links weigert het ook een link zonder recipient_customer_id zolang de winkel minder dan 72 uur geleden is geïnstalleerd: error.details.reason is shop_too_new, available_at geeft aan wanneer zulke links mogelijk worden, en contact_email is het adres waarnaar je mailt om de wachttijd eerder te laten beoordelen. Een link met een ontvanger is direct toegestaan. |
| 403 | notifications_suspended | Productupdatemeldingen zijn voor deze shop opgeschort na spamklachten over eerdere campagnes. Opnieuw proberen helpt niet — neem contact op met de ondersteuning. |
| 404 | asset_not_found, mapping_not_found, order_not_found, category_not_found, job_not_found | De resource ontbreekt of hoort bij een andere shop. Bij POST /assets/uploads/{uploadId}/complete voor een multipart-upload kan asset_not_found error.details.reason bevatten: upload_not_found (geen open upload en geen geüpload object komt overeen met file_id, filename en upload_id) of parts_mismatch (er bestaat een object, maar niet het object dat de lijst met delen beschrijft). Een verkeerde filename komt hier terecht terwijl de upload nog open is, dus een gecorrigeerd verzoek rondt de upload af. Zonder details.reason zegt het bericht wat er ontbreekt; een file_id die geen upload van deze shop aanwijst (een onvoltooide placeholder wordt na 24 uur verwijderd), vereist een nieuwe upload. |
| 404 | notification_not_found | De productupdatemelding ontbreekt of hoort bij een andere shop. |
| 404 | preorder_not_found | De voorbestelling ontbreekt of hoort bij een andere shop. Een schrijfactie op een koppeling waarvan de preorder_id geen voorbestelling van deze shop aanwijst, krijgt deze code ook. |
| 404 | share_link_not_found | De deellink bestaat niet of hoort bij een andere winkel. Bij POST /share-links geeft een file_id of mapping_id die in deze winkel nergens naar verwijst in plaats daarvan asset_not_found of mapping_not_found. |
| 409 | idempotency_conflict | Dezelfde sleutel is hergebruikt met een ander verzoek terwijl het eerste verzoek met die sleutel nog liep of nadat het was gelukt. |
| 409 | idempotency_conflict_in_progress | Dezelfde sleutel is verstuurd terwijl het eerste verzoek ermee nog loopt. Probeer het na een korte pauze opnieuw met dezelfde sleutel. Bij POST /assets/uploads/{uploadId}/complete duurt dit alleen zolang het eerste verzoek loopt, omdat elke mislukking van dat endpoint de sleutel vrijgeeft. 409 idempotency_conflict_in_progress kan ook duren totdat de sleutel verloopt (24 uur): wanneer een verzoek is geslaagd maar het antwoord niet kon worden opgeslagen om opnieuw af te spelen, of wanneer een verzoek is mislukt met een onverwachte serverfout. Een schrijfactie wordt nooit twee keer uitgevoerd, dus lees de resource om te zien of die is uitgevoerd in plaats van het opnieuw te proberen. |
| 409 | stamping_in_progress | Opnieuw verzenden is geblokkeerd zolang het PDF-stempelen nog loopt. |
| 409 | delivery_not_yet_released | De bestanden van de koper zijn nog niet vrijgegeven: voor het product is een vertraagde downloadlevering ingesteld, of de aankoop wordt vastgehouden door een voorbestelling. error.details.release_at is het ISO 8601-tijdstip waarop ze vrijkomen. Bij een aankoop met voorbestelling voegt het download-urls-endpoint error.details.bonus_available toe: als dat true is, geeft ?scope=bonus de bestanden terug die de koper al mag openen. Het grant-downloads-endpoint geeft een vertraagde bestelling eerder vrij, en een voorbestelling alleen met "release_preorders": true. |
| 409 | notification_not_cancellable | Alleen een productupdatemelding in de wachtrij kan worden geannuleerd. Deze is al begonnen met verzenden, voltooid, mislukt of geannuleerd — error.details.status zegt welke. |
| 409 | app_not_installed | Alva heeft geen actieve Shopify-sessie voor de shop, meestal omdat de app is verwijderd, dus een verzoek dat Shopify nodig heeft, kan niet worden uitgevoerd — het schrijven van een koppeling, of een productupdatemelding waarvan de notitie een metaveld noemt of die variant_ids meestuurt. Open de app of installeer hem opnieuw in de Shopify-admin en probeer het daarna opnieuw. |
| 409 | multiple_mappings_match | Een Shopify-id komt overeen met meer dan één koppeling, dus Alva kan niet bepalen welke je bedoelt. Bij POST /products/{id}/notifications somt error.details.ambiguous_variant_ids de gevraagde varianten op die door meer dan één koppeling worden bediend. |
| 409 | personalized_product | Het product is gepersonaliseerd. Personalisatie geldt voor het hele product, dus POST /mappings met shopify_variant_ids kan er geen variantspecifieke koppeling aan toevoegen (er wordt niets geschreven), en POST /products/{id}/notifications kan de kopers niet op de hoogte stellen, omdat elke bestelling een eigen bestand heeft. Een schrijfactie die voor een gepersonaliseerde koppeling een niet-lege stream_file_ids of stream_only_file_ids meestuurt, wordt op dezelfde manier geweigerd en schrijft niets, net als een schrijfactie die van een gepersonaliseerde koppeling een voorbestelling maakt (preorder_id, of een niet-lege bonuslijst). GET /orders/{shopify_order_id}/assignments/{purchaseId}/download-urls geeft deze code terug voor een aankoop van een gepersonaliseerd product waarvan de merchant de bestanden nog niet heeft geüpload: er worden geen URL's uitgegeven, en error.details.personalized_status is PENDING_UPLOAD of null. Probeer het opnieuw na de upload. |
| 409 | preorder_not_editable | De voorbestelling kan niet op deze manier worden gewijzigd: ze wordt al vrijgegeven of is al vrijgegeven, de vrijgave is over minder dan 5 minuten (bij het verplaatsen van de datum), ze is gearchiveerd (bij het koppelen), of een ander verzoek heeft haar als eerste gewijzigd. Wordt geretourneerd door PATCH /preorders/{id}, …/release, …/retry-failed (een voorbestelling waarvan de vrijgave nog niet is begonnen, heeft niets om opnieuw te proberen) en door preorder_id bij het schrijven van een koppeling. |
| 409 | preorder_conflicts_with_delay | Een koppeling kan niet tegelijk een voorbestelling zijn en een vertraagde downloadlevering hebben. Deze code krijgt een schrijfactie op een koppeling die beide meestuurt, die een voorbestelling toevoegt aan een koppeling met een vertraging zonder download_delay_seconds: 0 mee te sturen, of die een vertraging instelt op een koppeling die aan een voorbestelling gekoppeld blijft (stuur dan preorder_id: null mee). Er wordt niets geschreven. |
| 409 | preorder_has_purchases | POST /preorders/{id}/archive op een voorbestelling die nog niet is vrijgegeven en nog aankopen vasthoudt. Voorbestellingen worden gearchiveerd, nooit verwijderd. |
| 422 | storage_quota_exceeded | De upload of import zou de opslagquota overschrijden. |
| 422 | key_limit_reached | De shop heeft al het maximum van 25 actieve API-sleutels; trek er eerst een in. |
| 422 | withdrawal_consent_required | De shop heeft toestemming voor het EU-herroepingsrecht ingeschakeld en de bestelling heeft nog geen toestemmingsrecord; download-URL's worden uitgegeven zodra de klant toestemming geeft. |
| 422 | email_disabled | Klant-e-mails staan uit in de e-mailinstellingen van de app. Wordt geretourneerd door het opnieuw versturen van een bestelmail, door POST /orders/{id}/assignments met send_email: true (er wordt niets aangemaakt), door POST /products/{id}/notifications en als het notify_customers-resultaat bij het schrijven van een koppeling (de koppeling zelf wordt wel opgeslagen). Zet ze aan en probeer het opnieuw. |
| 422 | invalid_message | De productupdatenotitie heeft een regel geschonden: leeg, te lang (ook zodra de variabelen zijn ingevuld), een onbekende of niet-gesloten variabele, meer dan vijf verschillende metavelden, een link of e-mailadres (ook in de waarde van een metaveld), of een metaveld dat ontbreekt, te lang is of een type heeft dat niet in een e-mail kan worden weergegeven. error.details.errors[] benoemt elke regel; error.details.max_length is het maximum (2.000). Er is niets verzonden of geschreven. Bij het schrijven van een koppeling met notify_customers weigeren alleen de regels over de eigen tekst van de notitie de schrijfactie; een probleem met een metaveld wordt gerapporteerd in data.notification nadat de koppeling is opgeslagen. |
| 422 | no_downloadable_content | Geen enkele beoogde koppeling heeft bestanden, packs of links om aan te kondigen; keys-only en gepersonaliseerde koppelingen kunnen niet het onderwerp van een productupdate zijn. Met variant_ids noemt error.details.mapping_ids de koppelingen waarnaar die varianten zijn herleid, wanneer het product een andere koppeling heeft waarvoor een melding mogelijk is. |
| 422 | no_eligible_recipients | Niemand om te mailen: geen koper van de beoogde koppelingen is aangemeld. error.details.opted_out_count zegt hoeveel zich hebben afgemeld. Een gloednieuwe koppeling heeft nog geen kopers. |
| 422 | release_at_out_of_range | De release_at van een voorbestelling ligt, bij het aanmaken of bij het verplaatsen van de datum, minder dan 1 uur of meer dan 365 dagen vanaf nu. error.details.earliest_release_at en latest_release_at geven het toegestane venster op het moment van het verzoek. |
| 422 | preorder_bonus_not_member | Een item in preorder_bonus_asset_ids of preorder_bonus_link_ids hoort na het schrijven niet bij de bestanden van de koppeling (haar file_ids of de bestanden van haar pack_ids) of bij haar link_ids. error.details.asset_ids en link_ids noemen ze. Er wordt niets geschreven. |
| 422 | share_link_target_not_shareable | POST /share-links: het asset of de koppeling kan niet via een deellink worden weggegeven, en er wordt niets aangemaakt. error.details.reason geeft de reden: protected_pdf (een PDF die een product beveiligt met PDF-beveiliging), blocked_file_type (een installatieprogramma of script in een link zonder ontvanger; stuur recipient_customer_id mee om het te delen), personalized_product, product_inactive (zet het product op Actief), preorder_unreleased (het product, of een product waar het bestand bij hoort, zit in een voorbestelling die nog niet is vrijgegeven), nothing_to_share (geen bestanden of links, of ze worden allemaal weggelaten) of too_many_items (meer dan 500 bestanden en links). |
| 429 | rate_limited | De limiet voor API-sleutels of het opnieuw verzenden van bestellingen is bereikt. Bij POST /share-links betekent het ook dat de winkel in het afgelopen uur 100 deellinks heeft aangemaakt; Retry-After is het aantal seconden tot er weer een kan worden aangemaakt. |
| 429 | notification_cooldown | Eén productupdatemelding per product per 7 dagen, over al zijn varianten en elke bron — of er staat nog een campagne voor het product in de wachtrij of wordt verzonden. Dit is niet de token bucket: Retry-After kan tot zeven dagen zijn en error.details.next_available_at is het moment waarop het product weer vrij is. Probeer het niet automatisch opnieuw — plan de volgende aanroep op next_available_at. Een campagne annuleren reset de limiet niet; gebruik dry_run om een notitie te controleren voordat je verzendt. |
| 429 | too_many_active_notifications | De shop heeft al 5 productupdatemeldingen in de wachtrij of in verzending, over alle producten en elke bron. error.details.limit is het maximum en error.details.active_notification_ids somt die campagnes op, de oudste eerst. Er is geen Retry-After: poll GET /notifications/{id} voor een ervan en probeer het opnieuw zodra die klaar is. Een dry run wordt op dezelfde manier geweigerd; bij het schrijven van een koppeling wordt dit in plaats daarvan gerapporteerd in data.notification. |
| 429 | too_many_active_share_links | POST /share-links: de winkel heeft al 500 actieve deellinks. error.details.limit is het maximum. Er is geen Retry-After: trek een link in, of wacht tot er een verloopt of is opgebruikt, en probeer het dan opnieuw. |
| 500 | internal_error | Onverwachte serverfout. Bij POST /products/{id}/notifications geeft elke 500 de Idempotency-Key vrij, dus probeer hetzelfde verzoek opnieuw met dezelfde sleutel. Drie gevallen zijn daar te verwachten: Shopify kon de metavelden van het product voor de notitie niet teruggeven, Shopify kon de gevraagde variant_ids niet bevestigen, of het aanmaken wachtte meer dan 8 seconden achter de andere aanmaakverzoeken van de shop. Heeft de mislukte poging de campagne toch in de wachtrij gezet, dan wordt de nieuwe poging geweigerd met 429 notification_cooldown in plaats van een tweede te starten. Bij POST /assets/uploads/{uploadId}/complete geeft elke mislukking de sleutel ook vrij, en error.details.retryable zegt of een nieuwe poging kan slagen. Is het true, dan blijven de geüploade bytes bewaard: probeer hetzelfde verzoek opnieuw met dezelfde sleutel, met backoff en een beperkt aantal keren (bijvoorbeeld 5 pogingen verspreid over ongeveer een minuut), en begin daarna een nieuwe upload. Probeer het nooit zonder limiet opnieuw: een onverwachte serverfout wordt ook als herhaalbaar gemarkeerd en kan zich herhalen. Een nieuwe poging waarvan een eerdere poging de upload al had afgerond, geeft 200 terug met de asset; begin je in plaats daarvan een nieuwe upload, dan kan er een dubbele asset ontstaan als de mislukte poging die al had opgeslagen. Is het false, dan is de upload weggegooid: begin een nieuwe upload. details.retryable is alleen voor dit endpoint gedefinieerd: dat het ontbreekt bij een fout van een ander endpoint, betekent niet dat de fout definitief is. |
API-documentatie
Was dit nuttig?
Laatst bijgewerkt 2026-11-12