Error handling in Amazon OpenSearch Memory
This topic describes the errors that Amazon OpenSearch Memory returns and how to handle them in your application. For a list of common errors that apply to all AWS services, see Common Errors in the Amazon OpenSearch Memory API Reference.
Topics
Error components
When your application sends a request, OpenSearch Memory attempts to process it. If the
request succeeds, OpenSearch Memory returns an HTTP 200 OK status code with the
results of the operation. If the request fails, OpenSearch Memory returns an error with three
components:
-
An HTTP status code, such as
400. -
An exception name, such as
ResourceNotFoundException. -
An error message, such as
Space sp-02864597b164 not found.
The AWS SDKs propagate errors to your application as typed exceptions, so you can
handle each kind separately. ValidationException also carries a
reason code and, when a specific field is at fault, a
fieldList naming the fields. For more information, see Validation error reasons.
Error messages and codes
The following list describes the exceptions that OpenSearch Memory returns, grouped by HTTP status code. If OK to retry? is Yes, you can submit the same request again. If it is No, fix the problem on the client side before you submit a new request.
HTTP status code 400
An HTTP 400 status code indicates a problem with your request. Fix the
issue in your application before submitting the request again.
ValidationException
The request isn't valid. The reason and message describe
the problem, and fieldList names the fields that failed validation, if
any. Common causes: a value outside its allowed range, a query that uses an
unsupported query type or field, a CUSTOM strategy without an
extractionPrompt, an UpdateSpace request with an empty
memoryStrategies list, or an unusable customer managed key.
OK to retry? No
ResourceNotFoundException
The space, event, or memory doesn't exist, or the request's actorId,
sessionId, or strategyName doesn't match the stored
record. Also returned for a memory past its expiry, for a memory written with
CreateMemory that hasn't been indexed yet, and by
GetSpace for a short time after CreateSpace
returns.
OK to retry? Yes, if the resource was just created. Otherwise no.
ConflictException
The request conflicts with the current state of the resource. Causes: a
CreateSpace request with a name that another space in the account
and Region already has; an UpdateSpace or DeleteSpace
request on a space that is CREATING, UPDATING, or
DELETING; or a clientToken reused with different
request content. For more information, see Idempotent requests.
OK to retry? Yes, after the space leaves its transitional status. Otherwise no.
ServiceQuotaExceededException
A CreateSpace or UpdateSpace request would exceed a
quota, such as the number of strategies in a space. For more information, see Endpoints and quotas for Amazon OpenSearch Memory.
OK to retry? No
ThrottlingException
The request rate is too high, or AWS KMS throttled OpenSearch Memory's use of the space's customer managed key. The AWS SDKs retry throttled requests automatically.
OK to retry? Yes
AccessDeniedException
The caller doesn't have permission for the osm: action on the space,
or, for a space with a customer managed key, doesn't have permission to use the key. The
message names the action and resource. For more information, see Troubleshooting OpenSearch Memory identity and access.
OK to retry? No
HTTP status code 500
InternalServerException
OpenSearch Memory couldn't process the request because of an internal error. The AWS SDKs retry this error automatically.
OK to retry? Yes
Validation error reasons
A ValidationException includes a reason that identifies the
rule the request broke. OpenSearch Memory might add reasons over time, so treat a value you
don't recognize as a general validation failure.
| Reason | Meaning |
|---|---|
fieldValidationFailed |
A field's value is outside its allowed range or format.
fieldList names the field. |
unsupportedParameter |
The request includes a parameter that this operation doesn't accept. |
disallowedQueryType |
The query uses a query type that isn't supported, such as
knn or wildcard. |
unknownField |
The query or sort refers to a field that doesn't exist. |
unsupportedField |
The query or sort refers to a field that exists but can't be used in that position. |
nonFilterableField |
The query or sort refers to the actor or session field. Use the
actorId and sessionIds parameters
instead. |
fieldIndexMismatch |
The field can't be used with that query type, for example a
neural query on a text field. |
unboundedPattern |
A query pattern isn't bounded and would be too costly to run. |
queryNestingTooDeep |
A bool query nests more than 5 levels, or the query has
too many clauses. |
queryBodyTooLarge |
The query and sort exceed 64 KB together,
or exceed a clause, value, or function limit, or the response would
exceed 5 MiB. |
malformedQueryBody |
The query or sort can't be parsed. |
invalidNextToken |
The pagination token isn't valid, or paging went past the limit on results you can page through. |
other |
Another validation failure, such as an unusable customer managed key. Read the message. |
Error retries and exponential backoff
Many errors are transient. The AWS SDKs retry ThrottlingException and
InternalServerException automatically with exponential backoff: each
retry waits longer than the one before it, with some random jitter. If you don't use an
SDK, implement the same approach. Start with a short delay such as 50 milliseconds,
double it on each retry, and stop after a reasonable number of attempts.
Two situations call for retries that the SDKs don't do for you:
-
Right after
CreateSpace,GetSpacecan returnResourceNotFoundExceptionfor a short time. Use theSpaceActivewaiter, which handles this, rather than callingGetSpaceonce. -
Right after
CreateMemory, GetMemory returnsResourceNotFoundExceptionuntil the memory is indexed. Poll with backoff if your application needs the memory immediately.
Idempotent requests
CreateSpace, CreateEvent, and CreateMemory
accept a clientToken, a unique string that identifies the request. If a
request with the same token is received again within 2 hours, OpenSearch Memory returns the
result of the first request instead of creating a second resource. The AWS SDKs and
the AWS CLI generate a token for you and reuse it when they retry a request, so a network
timeout can't create a duplicate space, event, or memory.
The retried request must be the same request. If the same token arrives with
different content, the request fails with ConflictException.
Without a client token, a retry of CreateEvent stores the event again,
and if you omitted sessionId, the copy lands in a new session. Reuse the
same sessionId on every CreateEvent of a conversation so that
it stays in one session.
The other operations handle retries as follows:
| Operation | Retry behavior |
|---|---|
UpdateSpace |
Doesn't take a token. A retry while the space is
UPDATING fails with ConflictException; a
retry after the update completes changes nothing, because the space
already has the values. |
| UpdateMemory | Doesn't take a token. A retry applies the same change again, with the same result. |
DeleteSpace |
A retry while the space is DELETING returns
DELETING again. Safe to retry. |
| DeleteEvent, DeleteMemory | A retry after the delete succeeded returns
ResourceNotFoundException. Treat that error as
success. |
| Read operations | Safe to retry. |
Batch operations and error handling
BatchGetEvent reads up to 10 events in one call. It doesn't fail the
whole call when one event can't be returned. Instead, the response lists the events it
could return in events, in the order you requested them, and the rest in
errors, each with an errorCode:
| Error code | Meaning | Action |
|---|---|---|
RESOURCE_NOT_FOUND |
The event doesn't exist, or doesn't belong to the
actorId or sessionId in the
request. |
Don't retry. |
THROTTLING |
The read was throttled. | Retry the event with backoff. |
ACCESS_DENIED |
The caller can't decrypt the event under the space's customer managed key. | Fix the key permissions. |
INTERNAL_SERVER |
The event couldn't be read. | Retry the event with backoff. |
Check errors on every response, and retry only the events that failed
with a retryable code. If the space's customer managed key is disabled or deleted, the whole call
fails with ValidationException, as GetEvent does.