HTTP status codes
400Bad requestMalformed JSON, invalid parameters, or conflicting selectors.401UnauthorizedThe API key is missing or invalid.403ForbiddenThe key lacks scope or violates an IP restriction.404Not foundThe resource is missing or not visible to this account.409ConflictA crawl idempotency key changed intent, a source is already active or unavailable, or its type cannot be run.429Too many requestsThe configured hourly limit is exhausted.410Cursor expiredCatalog cursors expire after 24 hours; start a fresh traversal.502Bad gatewayA source dispatch failed, returned an invalid response, or was not recorded.503Temporarily unavailableAuthentication, rate limiting, source runs, or an owner service is unavailable.504Gateway timeoutAmygdala timed out while dispatching a source.Current response shapes
Product and matched-offer reads use a structured error on authentication, permissions, input, gateway, and owner-service failures. Preserve the X-Request-ID response header for support.
{"error":{"code":"ambiguous_sku","message":"More than one product in this channel has the supplied SKU.","details":{"parameter":"sku"}}}Handle invalid_cursor (400), source_changed (409), cursor_expired (410), and representation_unavailable (503). A representation with reason record_too_large requires support instead of repeated retries. Missing or inaccessible products, offers, and SKUs return 404.
Legacy Core routes can return a simple string message:
{
"error": "missing API key"
}Channel source routes return a structured public error with a stable machine code and a sanitized message:
{
"error": {
"code": "source_type_not_runnable",
"message": "This source type cannot be run"
}
}Tracked crawl routes also return a structured error with a stable machine code:
{
"status": false,
"error": {
"code": "idempotency_conflict",
"message": "The idempotency key was already used"
}
}When starting a source run, handle these stable failure codes:
source_run_conflict(409): the source is already active or otherwise unavailable.source_type_not_runnable(409): the source type does not support manual runs.source_dispatch_unavailable(502): Amygdala could not dispatch the source.invalid_source_dispatch_response(502): Amygdala returned an invalid dispatch response.source_dispatch_not_recorded(502): the accepted dispatch was not found in the durable run ledger.source_dispatch_timeout(504): Amygdala timed out during dispatch.
Clients should tolerate both the legacy string and structured shapes while the public contract is being unified.