Response codes

Return code

A Return Code (RC) is a short integer accompanying an API response from the Service Gateway and Data Access microservices.

Each such response includes a single RC in the rc field of its out-of-band metadata (header). The provided RC specifies the success or failure of the completed request from the perspective of the given microservice. Successful responses are indicated by 0h. Responses with non-zero RCs indicate the request has failed.

When an RC from the group that begins with the prefix APP_ is returned, it indicates that the request has failed as a result of an error experienced at the application layer (API execution or aggregation). In this case, the application code (AC) entry of the response header will be populated in the ac field, providing further indication of the nature of the failure. All other non-zero RCs indicate framework or environmental failures (e.g. timeout or connectivity failures).

In addition to indicating request failure, non-zero RCs also provide a high-level indication of the nature of the failure. They can be used to provide more informative messages to end users, administrators, or logging systems. In addition, they are used by the Service Gateway to influence its handling of failures. For example, RCs that indicate that the failure is transient in nature or might succeed on an alternate target may be automatically retried by the Service Gateway when appropriate.

The list of return codes, and their meanings, are as follows:

name	value	description
`INCOMPLETE`	`-1h`	Operation not yet completed (never final RC).
`OK`	`0h`	Operation completed successfully.
`APP`	`5h`	Application error encountered (more details available).
`APP_DB`	`6h`	Application level DB error.
`APP_RETRY2`	`7h`	Application level recoverable condition (2^nd-stage retry).
`ERR`	`10h`	General error (typically indicates a bug).
`QUEUE`	`11h`	Error enqueuing message.
`NOT_SUPPORTED`	`12h`	Service class or API not supported.
`VERSION`	`13h`	Service version not compatible.
`SERIALIZE`	`14h`	Serialization error.
`DB`	`20h`	General database error.
`DB_QUEUE`	`21h`	Error enqueuing to DB process.
`DB_NO_RETRY`	`22h`	General database error (do not retry).
`REDIR`	`23h`	Error encountered redirecting request.
`REDIR_TTL`	`24h`	Redirect TTL hops exhausted.
`NO_SHARD`	`26h`	Failure determining appropriate shard.
`NO_MEM`	`30h`	Out of memory.
`PAUSED`	`31h`	System is currently paused.
`COMM`	`40h`	General protocol or comm failure (typically indicates a bug).
`CONN_FAILED`	`41h`	Unable to connect to server.
`DISCONNECT`	`42h`	Server disconnected.
`SHUTDOWN`	`43h`	Local application is shutting down.
`IO`	`44h`	Communications error sending or receiving data.
`TIMEOUT`	`45h`	Operation timeout.
`BUSY`	`46h`	Session already busy with a service.
`COMM_INIT`	`47h`	Communications initialization failure.
`CANCEL`	`48h`	Operation cancelled.
`WOULD_BLOCK`	`49h`	Operation would block.
`PROTOCOL_VER`	`50h`	Protocol version obsolete.
`PENDING_IO`	`51h`	Another operation in progress on this channel.
`ASYNC`	`52h`	Asynchronous operation cannot be completed.
`CONN`	`53h`	General connection management error.
`CHNL_CLOSED`	`54h`	Attempt to perform I/O after channel has been closed.
`CONN_EXHST`	`55h`	Connections for destination exhausted.
`NO_DEST`	`56h`	No suitable destination could be found.
`CHRONO`	`57h`	Session chronology mismatch.
`NOT_READY`	`58h`	Connection not ready.
`PARTIALS`	`100h`	Aggregation, where partial results are sent in the payload
`PARTIALS_SUB`	`101h`	One or more sub-requests failed, details in payload
`PARTIALS_RESUME`	`102h`	Aggregation failed in the resume after completion of sub-requests, details in payload

Note: Descriptions of payloads if return code is one of PARTIALS_* can be found here.

Application code

An Application Code (AC) is a short integer used to indicate success or failure of application processing stages to the Service Gateway and Data Access microservices, and accompanies responses to API requests.

A zero value (0h) indicates that application processing was successful. A non-zero AC indicate some form of application level failure.

API requests which encounter an application-level failure will indicate an RC from the APP_ group of return codes. In addition, an ai entry may also be present in the header containing arbitrary application data related to the failure that may benefit any callers with sufficient intimacy with the application to expect and interpret the provided application information.

The list of application codes, and their meanings, are as follows:

name	value	description
`OK`	`0h`	Successful completion.
`CONTINUE`	`1h`	Asynchronous resume expected (never final AC).
`ERR`	`10h`	General error.
`TYPE`	`11h`	Type error.
`LOCK`	`12h`	Object could not be locked.
`NO_LOCK`	`13h`	Object no longer locked.
`INPUT`	`14h`	Input error.
`DUP_REQUEST`	`15h`	Duplicate request ignored.
`MULT_ERRS`	`16h`	Multiple errors encountered (array provided).
`NOT_FOUND`	`17h`	Object not found.
`NONCE`	`18h`	Not implemented.
`MEMORY`	`19h`	Memory exhausted.
`NOT_READY`	`20h`	Server not ready.
`STATE`	`21h`	Improper operation state.
`BIND`	`22h`	Data binding error.
`ARG`	`23h`	Illegal argument.
`LIMIT`	`24h`	Size or count limit exceeded.
`SEQ`	`25h`	Sequence error.
`MODE`	`26h`	Improper operational mode.
`DOMAIN`	`27h`	Domain error.
`RANGE`	`28h`	Range error.
`ALIGN`	`29h`	Alignment error.
`MISMATCH`	`30h`	Data mismatch.
`PERM`	`40h`	Insufficient permission.
`XPERM`	`41h`	Insufficient permission (serious).
`AUTH`	`42h`	Catastrophic authentication failure.
`SESSION`	`43h`	Session state invalid.
`EXPIRED`	`44h`	Permission expired.
`NO_SPACE`	`50h`	Out of disk space.
`FILE_PATH`	`51h`	Bad path or file name.
`FILE_NAME`	`52h`	Name in use.
`FILE`	`53h`	General file operation failure.
`FILE_IO`	`54h`	File I/O error.
`FILE_MODE`	`55h`	Unable to acquire requisite share mode.
`FILE_DAMAGED`	`56h`	File damaged.
`FILE_ACCESS`	`57h`	Access denied.
`FILE_NF`	`58h`	File not found.
`FILE_RENAME`	`59h`	File rename error.
`FILE_MOVE`	`60h`	File move error.
`FILE_COPY`	`61h`	File copy error.
`DB`	`70h`	General database error.
`DUP_KEY`	`71h`	Duplicate key.
`REL_OVERLAP`	`72h`	Relationship overlap.
`REF`	`73h`	Extant reference.
`TABLE`	`74h`	Invalid table name.
`COLUMN`	`75h`	Invalid column name