Error codes for the HTTP client SDK
When a request to send, consume, or acknowledge messages fails, the ApsaraMQ for RocketMQ HTTP client SDK returns one of the following error codes. Use this reference to identify the cause and resolve the issue.
Error categories
The following table groups error codes by handling strategy:
| Category | Error codes | Action |
|---|---|---|
| Authentication and authorization | AccessDenied, InvalidAccessKeyId, SignatureDoesNotMatch | Verify your AccessKey pair and signing method. Do not retry without fixing the issue. |
| Request validation | InvalidArgument, InvalidAuthorizationHeader, InvalidDateHeader, InvalidDigest, InvalidRequestURL, InvalidQueryString, MalformedXML, MissingAuthorizationHeader, MissingDateHeader, MissingReceiptHandle, ReceiptHandleError, HTTPForbidden | Fix the request parameters or headers. Do not retry without changes. |
| Server and transient | InternalError, InternalServerError, MessageNotExist, TimeExpired, QpsLimitExceeded | Retry with exponential backoff, or reduce your request rate and retry. |
Authentication and authorization errors
AccessDenied
| Attribute | Value |
|---|---|
| HTTP status code | 403 |
| Error message | The OwnerId that your Access Key Id associated to is forbidden for this operation. |
Cause: The account associated with your AccessKey ID does not have permission for this operation.
Resolution:
Verify that the AccessKey ID and AccessKey secret are correct.
Confirm the account has the required permissions for this API action.
Make sure the AccessKey pair is active and not disabled.
InvalidAccessKeyId
| Attribute | Value |
|---|---|
| HTTP status code | 403 |
| Error message | The AccessKey Id you provided is not exist. |
Cause: The specified AccessKey ID does not exist.
Resolution: Verify that the AccessKey ID is correct. To create or manage AccessKey pairs, see Create an AccessKey pair.
SignatureDoesNotMatch
| Attribute | Value |
|---|---|
| HTTP status code | 403 |
| Error message | The request signature we calculated does not match the signature you provided. Check your key and signing method. |
Cause: The request signature calculated by the server does not match the signature in the request.
Resolution: Check your AccessKey secret and signing method. For the correct signing algorithm, see Request signatures.
Request validation errors
InvalidAuthorizationHeader
| Attribute | Value |
|---|---|
| HTTP status code | 400 |
| Error message | The Authorization header format is invalid. |
Cause: The Authorization header is not in the expected format.
Resolution: Correct the header format. For details, see Request signatures.
MissingAuthorizationHeader
| Attribute | Value |
|---|---|
| HTTP status code | 400 |
| Error message | Authorization header is required. |
Cause: The request does not include the Authorization header.
Resolution: Add the Authorization header to your request. For details, see Common parameters.
InvalidDateHeader
| Attribute | Value |
|---|---|
| HTTP status code | 400 |
| Error message | The Date header format is invalid. |
Cause: The Date header is not in the expected format.
Resolution: Correct the header format. For details, see Common parameters.
MissingDateHeader
| Attribute | Value |
|---|---|
| HTTP status code | 400 |
| Error message | Date header is required. |
Cause: The request does not include the Date header.
Resolution: Add the Date header to your request. For details, see Common parameters.
InvalidArgument
This error code covers multiple validation failures. Match the error message to identify the specific issue.
XML schema validation failure
| Attribute | Value |
|---|---|
| HTTP status code | 400 |
| Error message | The XML you provided did not validate against our published schema, cause by Element *{parameter}*. |
Cause: The XML request body contains an element that does not conform to the published schema. The *{parameter}* placeholder identifies the invalid element.
Resolution: Fix the XML element indicated in the error message. For valid XML structures, see:
Parameter value out of range
| Attribute | Value |
|---|---|
| HTTP status code | 400 |
| Error message | The value of Element *{parameter}* must be between Low *{min}* and High *{max}* seconds/bytes. |
Cause: The specified parameter value falls outside the allowed range. The *{parameter}*, *{min}*, and *{max}* placeholders identify the parameter name and valid range.
Resolution: Set the parameter to a value within the range specified in the error message.
Message body too large
| Attribute | Value |
|---|---|
| HTTP status code | 400 |
| Error message | The length of message should not be larger than MaximumMessageSize. |
Cause: The message body exceeds the maximum allowed size.
Resolution: Reduce the message body size to within the MaximumMessageSize limit. For details, see Operation for sending messages.
InvalidDigest
| Attribute | Value |
|---|---|
| HTTP status code | 400 |
| Error message | The Content-MD5 you specified is invalid. |
Cause: The Content-MD5 header value does not match the request body content.
Resolution: Recalculate the MD5 digest of the request body and update the header, or omit the Content-MD5 header.
InvalidRequestURL
| Attribute | Value |
|---|---|
| HTTP status code | 400 |
| Error message | Http request URL format invalid. |
Cause: The request URL format is incorrect.
Resolution: Correct the URL format. For valid URL structures, see:
InvalidQueryString
| Attribute | Value |
|---|---|
| HTTP status code | 400 |
| Error message | Http request URL contains invalid querystring item "*{parameter}*". |
Cause: The request URL contains an unsupported query string parameter. The *{parameter}* placeholder identifies the invalid item.
Resolution: Remove the invalid query string parameter. For valid URL structures, see:
MalformedXML
| Attribute | Value |
|---|---|
| HTTP status code | 400 |
| Error message | The XML you provided was not well-formed. |
Cause: The XML in the request body is not well-formed (for example, it has missing closing tags or incorrect nesting).
Resolution: Validate your XML before sending the request. For valid XML structures, see:
MissingReceiptHandle
| Attribute | Value |
|---|---|
| HTTP status code | 400 |
| Error message | ReceiptHandle is required. |
Cause: The request does not include the required ReceiptHandle parameter.
Resolution: Include the ReceiptHandle obtained from a previous consume operation. For details, see:
ReceiptHandleError
| Attribute | Value |
|---|---|
| HTTP status code | 400 |
| Error message | The receipt handle you provide is not valid. |
Cause: The ReceiptHandle value is malformed or corrupted.
Resolution: Use the exact ReceiptHandle value returned by a consume operation. Do not modify or truncate it. For details, see:
HTTPForbidden
| Attribute | Value |
|---|---|
| HTTP status code | 400 |
| Error message | Consume message through HTTP and TCP at the same time is forbidden. |
Cause: The same group ID is being used by both the TCP client SDK and the HTTP client SDK at the same time.
Resolution: Use separate group IDs for the TCP client SDK and the HTTP client SDK. A single group ID cannot be shared across both protocols concurrently.
Server and transient errors
InternalError
| Attribute | Value |
|---|---|
| HTTP status code | 500 |
| Error message | Interal error. |
Cause: An internal error occurred on the server.
Resolution: Retry the request with exponential backoff. If the error persists, submit a ticket to contact technical support.
InternalServerError
| Attribute | Value |
|---|---|
| HTTP status code | 500 |
| Error message | Interal error. |
Cause: An internal server error occurred.
Resolution: Retry the request with exponential backoff. If the error persists, submit a ticket to contact technical support.
MessageNotExist
This error code has two variants:
No messages available
| Attribute | Value |
|---|---|
| HTTP status code | 404 |
| Error message | Message not exist. |
Cause: No messages are available in the topic.
Resolution: This is expected behavior when the topic has no pending messages. Retry after a short interval using a polling strategy.
Receipt handle expired
| Attribute | Value |
|---|---|
| HTTP status code | 404 |
| Error message | The receipt handle you provided has expired. |
Cause: The consumer did not acknowledge the message within the visibility timeout, and the ReceiptHandle has expired.
Resolution: Consume the message again to get a new ReceiptHandle, then acknowledge it before the visibility timeout expires. To prevent this error, make sure message processing completes within the visibility timeout window.
TimeExpired
| Attribute | Value |
|---|---|
| HTTP status code | 408 |
| Error message | The http request you sent is expired. |
Cause: More than 15 minutes elapsed between when the request was sent and when the ApsaraMQ for RocketMQ server received it.
Resolution: Check your local system clock for accuracy. Synchronize the system time with a reliable NTP server and verify that network latency is within acceptable limits.
QpsLimitExceeded
| Attribute | Value |
|---|---|
| HTTP status code | 400 |
| Error message | The QPS limit *{limit}* is exceeded. |
Cause: The number of requests per second for a topic exceeds the queries-per-second (QPS) limit. The *{limit}* placeholder shows the current per-topic QPS limit.
Resolution:
Implement request throttling with exponential backoff.
Distribute requests across multiple topics if possible.
To raise the QPS limit, submit a ticket.
For current per-topic QPS limits, see Limits.