Skip to content
ShopentlyLearn
English

Error codes

If a request fails, check the error code in the response. Expand it in the list below to find out what happened and what to do next. Each error also includes an example response and guidance on retrying the request.

400request.malformedThe request cannot be parsed.
What to do
Check JSON syntax, URL encoding and the structure of the request.
Retry policy
Retry after correcting the request.
Response 
{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsThe API key or access token is invalid, expired or revoked.
What to do
Check the store URL and credential. Obtain a fresh token with an active API key.
Retry policy
Retry after correcting authentication; avoid repeated invalid token requests.
Response 
{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.requiredThe required Authorization header is missing or its scheme is incorrect.
What to do
To issue or revoke a token, use your API key with ApiKey in the Authorization header. For other requests, use the access token with Bearer.
Retry policy
Retry after supplying the correct header.
Response 
{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverifiedThe service could not establish a trusted client IP address.
What to do
Check which IP address your integration uses to connect to the API. If the error persists, contact Shopently technical support.
Retry policy
Retry once the problem identifying the IP address has been resolved.
Response 
{
  "error": {
    "code": "authorization.client_ip_unverified",
    "fields": null,
    "message": "The client IP address could not be verified."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.ip_not_allowedThe source IP address is outside the key's allowed address list.
What to do
Use an approved source address or ask an authorized administrator to edit the key's IP list.
Retry policy
Retry only after the address is allowed.
Response 
{
  "error": {
    "code": "authorization.ip_not_allowed",
    "fields": null,
    "message": "Access from this IP address is not allowed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.scope_deniedThe key does not have an effective permission required for this operation.
What to do
Check the operation's required and conditional permissions, key grants and issuer access.
Retry policy
Retry after an authorized administrator grants the required access.
Response 
{
  "error": {
    "code": "authorization.scope_denied",
    "fields": null,
    "message": "The required permission has not been granted."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.api_disabledAPI access is disabled for this store.
What to do
Ask the store owner to check the active plan and API availability.
Retry policy
Do not retry until API access is enabled.
Response 
{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceededThe change would exceed a limit of the current plan.
What to do
Check the applicable resource limit and adjust the intended change or plan.
Retry policy
Retry after resolving the limit; use a new idempotency key if the request changes.
Response 
{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabledThe current plan does not include this operation.
What to do
Check the minimum plan shown for the operation.
Retry policy
Retry after the plan allows the operation and the key has the required permissions.
Response 
{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blockedA plan limit blocks this particular resource.
What to do
Ask the owner to resolve the resource's plan restriction.
Retry policy
Do not repeat the same request while the resource remains blocked.
Response 
{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_foundThe resource is absent, deleted or not available under the supplied identifier.
What to do
Check the store, resource path and identifier. Use identifiers returned by this store.
Retry policy
Retry only after correcting the target or confirming that it exists.
Response 
{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowedThe endpoint does not support this HTTP method.
What to do
Use the documented method; the Allow header identifies the supported methods.
Retry policy
Do not retry the unsupported method.
Response 
{
  "error": {
    "code": "request.method_not_allowed",
    "fields": null,
    "message": "This method is not supported for this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409idempotency.key_reusedThis idempotency key belongs to a different request.
What to do
Find the original operation. Use a new key only for an intentionally new logical operation.
Retry policy
Do not retry a changed payload with the conflicting key.
Response 
{
  "error": {
    "code": "idempotency.key_reused",
    "fields": null,
    "message": "This idempotency key was used with a different request."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.already_existsA unique value conflicts with an existing resource.
What to do
Read the existing resource and decide whether to use it or choose a different unique value.
Retry policy
Do not repeat the same conflicting creation.
Response 
{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_useOther resources still depend on this resource.
What to do
Review the dependencies and remove or change them through supported operations before deleting.
Retry policy
Retry after resolving dependencies.
Response 
{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflictThe current business state prevents this change.
What to do
Read the current state and choose a valid business transition.
Retry policy
Do not automatically force or repeatedly submit the conflicting change.
Response 
{
  "error": {
    "code": "resource.state_conflict",
    "fields": null,
    "message": "The current resource state does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.version_conflictAnother write changed the resource after the version you read.
What to do
Read the latest state, reconcile your change and submit the new expected_version.
Retry policy
Use a new idempotency key for the revised operation; do not blindly overwrite.
Response 
{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409storage.limit_reachedThe store has reached its upload storage limit. Free some space or increase the limit.
What to do
The store has reached its upload storage limit. Free some space or increase the limit.
Retry policy
Retry smaller, valid operations with their own idempotency keys.
Response 
{
  "error": {
    "code": "storage.limit_reached",
    "fields": null,
    "message": "The upload storage limit is reached."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_largeThe request exceeds the size limit.
What to do
Reduce the payload or split the work into supported individual operations.
Retry policy
Retry smaller, valid operations with their own idempotency keys.
Response 
{
  "error": {
    "code": "request.too_large",
    "fields": null,
    "message": "The request exceeds the size limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

415request.unsupported_media_typeThe media type or content encoding is unsupported.
What to do
For JSON writes, use Content-Type: application/json and a supported uncompressed body.
Retry policy
Retry after correcting the media type or encoding.
Response 
{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

416request.range_not_satisfiableConstraints: Range
What to do
Range: bytes=0-(size_bytes-1)
Retry policy
Retry after correcting the request.
Response 
{
  "error": {
    "code": "request.range_not_satisfiable",
    "fields": null,
    "message": "The requested byte range is unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failedOne or more fields or parameters fail validation.
What to do
Inspect error.fields, then check required fields, nullability, identifiers and allowed values.
Retry policy
Retry a corrected request; a changed write is a new logical operation.
Response 
{
  "error": {
    "code": "request.validation_failed",
    "fields": null,
    "message": "Some request parameters are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.queue_fullThe short API queue is full; the request has not started execution.
What to do
Queue requests and respect the Retry-After response header.
Retry policy
Wait at least the number of seconds given in Retry-After. If you retry a write, keep the same request body and the same Idempotency-Key value.
Response 
{
  "error": {
    "code": "capacity.queue_full",
    "fields": null,
    "message": "The API is busy. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.wait_timeoutThe API queue wait expired; the request has not started execution.
What to do
Queue requests and respect the Retry-After response header.
Retry policy
Wait at least the number of seconds given in Retry-After. If you retry a write, keep the same request body and the same Idempotency-Key value.
Response 
{
  "error": {
    "code": "capacity.wait_timeout",
    "fields": null,
    "message": "The API could not start this request in time. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429rate_limit.exceededThe request rate exceeds the applicable limit.
What to do
Queue requests and respect the Retry-After response header.
Retry policy
Wait at least the number of seconds given in Retry-After. If you retry a write, keep the same request body and the same Idempotency-Key value.
Response 
{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.errorAn unexpected service error occurred.
What to do
Wait a moment before retrying the request. If error 500 occurs again, contact Shopently technical support. Include the request ID in your message.
Retry policy
You can retry fetching data after a short pause. When retrying a write, use the same Idempotency-Key value and keep the request body unchanged.
Response 
{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_responseThe gateway did not receive a valid API response.
What to do
Keep the request identifier. A failed response does not prove that a write was not applied.
Retry policy
Use bounded backoff; repeat the same logical write with its original Idempotency-Key and payload.
Response 
{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableThe API is temporarily unable to handle the request.
What to do
If the response includes a Retry-After header, wait the specified number of seconds before trying again. Otherwise, try again in a moment. If the error keeps occurring, contact Shopently technical support and include the request ID.
Retry policy
Retry after waiting as described above. When retrying a write, use the same Idempotency-Key value and keep the request body unchanged.
Response 
{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeoutThe gateway timed out while awaiting the API.
What to do
If the request changed data, check whether the changes were saved in the store. A missing response does not mean the write failed. If the error keeps occurring, contact Shopently technical support and include the request ID.
Retry policy
You can retry fetching data after a short pause. When retrying a write, use the same Idempotency-Key value and keep the request body unchanged.
Response 
{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}