Error Codes and Messages

Creators API returns structured error responses that provide information about request validation failures, authentication issues, and server-side errors. All error messages are returned in English for all marketplaces.

Error Response Structure

All errors follow a consistent JSON structure with these elements:

• Type: The exception type identifier for clients to programmatically identify the exception (e.g., ValidationException).

• Message: A human-readable description of the error to help you debug the issue.

• Reason (for ValidationException, AccessDeniedException, and UnauthorizedException): A machine-readable code that categorizes the specific type of validation, access, or authentication error.

• Additional fields (context-dependent): Some errors include additional fields like resourceId, resourceType, fieldList, or retryAfterSeconds.

Example Error Response

{
  "type": "ValidationException",
  "message": "Partner tag in the request is invalid or is not mapped to the store associated with your credential.",
  "reason": "InvalidPartnerTag"
}

Exception Types

It is also possible to submit a valid request and still have errors. In such cases, the HTTP Status Code is 200 Success, however, the response might contain errors. For more information, refer Processing of Errors.

HTTP Status Code Ranges

4xx Client Errors

These errors indicate issues with the request sent to Creators API:

• 400 Bad Request - ValidationException (invalid input, missing fields, parsing errors)

• 401 Unauthorized - UnauthorizedException (missing or invalid authentication)

• 403 Forbidden - AccessDeniedException (insufficient permissions or ineligible account)

• 404 Not Found - ResourceNotFoundException (requested resource doesn't exist)

• 429 Too Many Requests - ThrottleException (rate limiting)

5xx Server Errors

These errors indicate issues on the Creators API server side:

• 500 Internal Server Error - InternalServerException (unexpected server-side error)

Error Reason Codes

The following sections provide detailed descriptions and example messages for each reason code.

ValidationException Reasons

AccessDeniedException Reasons

UnauthorizedException Reasons

ThrottleException Details

When receiving a ThrottleException, the error response may include a retryAfterSeconds field indicating how long to wait before retrying:

{
  "type": "ThrottleException",
  "message": "The request was denied due to request throttling. Please verify the number of requests made per second.",
  "retryAfterSeconds": 60
}

ResourceNotFoundException Details

When receiving a ResourceNotFoundException, the error response includes resourceType and resourceId fields:

• resourceType: The type of resource that was not found

• resourceId: The identifier of the resource that was not found

Sample Error Scenarios

Invalid PartnerTag

HTTP/1.1 400 Bad Request
{
  "type": "ValidationException",
  "message": "Partner tag in the request is invalid or is not mapped to the store associated with your credential.",
  "reason": "InvalidPartnerTag"
}

Invalid Associate

HTTP/1.1 400 Bad Request
{
  "type": "ValidationException",
  "message": "Your credential is not linked to the partner tag in the request for the given Marketplace.",
  "reason": "InvalidAssociate"
}

Missing or Invalid Field

HTTP/1.1 400 Bad Request
{
  "type": "ValidationException",
  "message": "Request validation failed.",
  "reason": "FieldValidationFailed",
  "fieldList": ["partnerTag"]
}

Expired Token

HTTP/1.1 401 Unauthorized
{
  "type": "UnauthorizedException",
  "message": "Authentication token has expired.",
  "reason": "TokenExpired"
}

Invalid Token

HTTP/1.1 401 Unauthorized
{
  "type": "UnauthorizedException",
  "message": "The authentication token is invalid or malformed.",
  "reason": "InvalidToken"
}

Ineligible Associate

HTTP/1.1 403 Forbidden
{
  "type": "AccessDeniedException",
  "message": "Your account does not currently meet the eligibility requirements.",
  "reason": "AssociateNotEligible"
}

Rate Limiting

This error occurs when you exceed the allowed number of requests per second. When you receive a 429 status code, you should implement exponential backoff and retry the request after waiting.

HTTP/1.1 429 Too Many Requests
{
  "type": "ThrottleException",
  "message": "The request was denied due to request throttling. Please verify the number of requests made per second."
}

Item Not Accessible

HTTP/1.1 404 Not Found
{
  "type": "ResourceNotFoundException",
  "message": "No items found for the requested item IDs.",
  "resourceType": "Item",
  "resourceId": "B08N5WRWNW"
}

InternalServerException

HTTP/1.1 500 Internal Server Error
{
  "type": "InternalServerException",
  "message": "An unexpected error occurred while processing your request."
}

Token Endpoint Rate Limiting

The v2.x Cognito token endpoints (creatorsapi.auth.<region>.amazoncognito.com/oauth2/token) rate-limit each client to 300 requests per 5 minutes. This is the token endpoint itself — not Creators API — so the response shape differs from the errors above.

Access tokens are valid for 1 hour (expires_in: 3600). A correctly implemented client requests at most one token per hour, per credential, which is well under the limit. Hitting this error almost always means you are fetching a new token on every API call instead of reusing the cached one.

Response:

HTTP/1.1 429 Too Many Requests
Retry-After: 300
Content-Type: application/json

{
  "error": "too_many_requests",
  "error_description": "Your client has exceeded the token-endpoint rate limit. This usually indicates a missing token cache — access tokens are valid for 1 hour and should be reused. To resolve this, generate new credentials from Associates Central and configure them using the latest CreatorsAPI SDK or follow the guide at https://affiliate-program.amazon.com/creatorsapi/docs/en-us/troubleshooting/error-codes-and-messages."
}

Resolution:

1. Cache the access token until it expires; reuse it for every Creators API call.

2. If you run multiple processes or containers under the same Client ID, share one cache across them.

3. Wait the number of seconds in the Retry-After header before retrying.

4. Consider migrating to the official SDKs — they handle token caching and renewal automatically.

The v3.x Login with Amazon token endpoints (api.amazon.com/auth/o2/token, etc.) are not subject to this specific limit, but the same caching guidance applies.

Migrating from Product Advertising API?

If you are still calling the Product Advertising API (PA-API 5.0) and receive the following error:

HTTP/1.1 403 Forbidden
{
  "__type": "com.amazon.paapi5#AccessDeniedException",
  "Errors": [
    {
      "Code": "AccessDenied",
      "Message": "Product Advertising API is deprecated. Please migrate to Creators API using the migration guide at https://affiliate-program.amazon.com/creatorsapi/docs/en-us/migrating-to-creatorsapi-from-paapi."
    }
  ]
}

This means the Product Advertising API has been deprecated. See Migrating to Creators API from PAAPI for step-by-step instructions.

Best Practices

• Check HTTP status codes and parse the reason field for specific error handling

• Implement exponential backoff retry for 429 and 500 errors

• Implement token refresh logic for TokenExpired errors

• Cache access tokens for their full lifetime (1 hour) to avoid hitting the token endpoint rate limit

For more information, see Processing of Errors and Troubleshooting Applications.