AppError codes

This section documents Akkadia’s application error codes used by AppError.

In Akkadia, we treat an error code as a stable, searchable classification key:

It’s safe to log and aggregate.
It can act as a documentation key (what this page is for).
It should remain stable even if the error message changes.

This catalog is evolving

Not every error is documented yet. New codes are added continuously as Akkadia grows. If you encounter a code that isn’t listed here, treat it as a valid code and handle it gracefully (log it, attach meta.via, and report it).

Where codes live

AppErrorCodes is defined in the shared package:

shared/common/src/error/codes.ts

Docs pages are organized by the same top-level domains (e.g. RPC, TERRAIN):

/developers/error-codes/codes/<domain>/...

How codes are used

1) When you create a domain error (no original exception)

Use new AppError({ code: ... }) with a constant from AppErrorCodes.


import { AppError, AppErrorCodes } from '@aina/shared-common';
 
throw new AppError({
	code: AppErrorCodes.ROOM.NOT_FOUND,
	message: 'Room not found',
	status: 404,
	meta: { via: 'roomService.getRoom', params: { roomId } }
});

2) When you catch `unknown` and want to normalize

Use AppError.ensure() and provide a fallback code when appropriate.


import { AppError, AppErrorCodes } from '@aina/shared-common';
 
try {
	await doSomething();
} catch (e) {
	throw AppError.ensure(e, {
		code: AppErrorCodes.RPC.BASE_CALL_FAILED,
		status: 500,
		meta: { via: 'rpc.base.call' }
	});
}

Dynamic code helpers

Some codes are derived from runtime values (e.g. HTTP status). For consistency, we centralize those patterns as helpers.

AppErrorCodes.HTTP.status(status) → HTTP/<status> (for HTTP-like failures)
AppErrorCodes.AXIOS.httpStatus(status) → AXIOS/HTTP<status> (for Axios-originated HTTP failures)

See:

/developers/error-codes/codes/http/status
/developers/error-codes/codes/axios/http-status

Conventions

Prefer domain prefixes (RPC/..., TERRAIN/..., AUTH/...) for codes that can be shared across systems.
Put where it happened in meta.via (string or string array).
Keep message user-friendly but don’t depend on it for classification.