Error handling

Terra operations fail for a small number of well-defined reasons. The core library reports them as numeric codes; each binding surfaces them in whatever way is idiomatic for its language.

Error codes

Code	Name	Meaning
0	`E_SUCCESS`	Operation succeeded
1	`E_FAILED`	Operation failed for a reason with no more specific code
2	`E_DOMAIN`	An argument was outside its valid domain
3	`E_LATLNG_DOMAIN`	Latitude or longitude outside the valid range
4	`E_RES_DOMAIN`	Resolution outside 0–14
5	`E_CELL_INVALID`	The value is not a well-formed Terra cell
6	`E_DIR_EDGE_INVALID`	The value is not a well-formed directed edge
7	`E_RES_MISMATCH`	Cells at different resolutions where equal resolution is required
8	`E_MEMORY_ALLOC`	Memory allocation failed
9	`E_MEMORY_BOUNDS`	Output array too small for the result
10	`E_OPTION_INVALID`	An option or mode argument was not recognised
11	`E_EXTENT`	The position falls outside the Terra coverage extent
12	`E_CHECK_FAILED`	A Terra Grid Code failed check-character validation

Codes 11 and 12 have no equivalent in general-purpose grid libraries and deserve attention.

E_EXTENT — outside coverage

Terra is a regional system. It covers Saudi Arabia and a GCC buffer, not the world. A coordinate in Cairo or Karachi is a valid coordinate and has no Terra cell.

This is the error most likely to surprise a new integration, because it is usually a symptom rather than a cause. The common triggers:

Latitude and longitude transposed. (46.72, 24.68) instead of (24.68, 46.72) lands in the Indian Ocean. This is by far the most frequent cause.
A datum or transformation error large enough to move the point out of the region.
A sentinel value such as (0, 0) reaching the indexer from an incomplete record.
Genuinely out-of-region data, which is a data scoping question rather than a defect.

Treat a sudden rise in E_EXTENT during a bulk load as an ingest problem, not as legitimately foreign data, until proven otherwise.

E_CELL_INVALID — malformed cell

A 64-bit value is not a Terra cell merely by being 64 bits. Validation checks that the mode is correct, reserved fields are zero, the resolution is 0–14, the base cell exists, digits at or below the resolution are 0–6, and digits beyond it are the unused marker 7.

The usual causes:

Hand-constructed indices where the resolution field was changed without updating the digits, or a digit was written without clearing the field first. Unused digits are 7, all bits set, so a bitwise OR cannot change them — the field must be cleared, then written.
Truncation through a type that cannot hold 64 bits. In JavaScript every Terra index exceeds Number.MAX_SAFE_INTEGER; storing one in a Number corrupts it silently. Use BigInt or the string form.
String round-trips that dropped the leading t or lost a character.

E_CHECK_FAILED — bad grid code

A Terra Grid Code failed its check character. This means a transcription error, not an unknown location.

Do not attempt correction. The check character detects errors; it does not identify which character is wrong, and a plausible-looking correction may be a different real location. Reject the code and ask for it again, indicating which part failed so the person knows what to re-read.

How each binding reports errors

C — Functions return a TerraError; results are written through an out-parameter. Always check the return value before reading the result.

TerraIndex cell;
TerraError err = latLngToCell(&coord, 8, &cell);
if (err != E_SUCCESS) { /* handle */ }

Python — Raises TerraError, or a subclass such as TerraDomainError or TerraExtentError. The numeric code is available on the exception.

try:
    cell = terra.latlon_to_cell(lat, lon, 8)
except terra.TerraExtentError:
    ...

JavaScript — Throws an Error carrying a terraCode property.

Go — Returns (result, error) in the conventional style. Errors are comparable against the package's sentinel values.

PostgreSQL — Raises a SQL exception. Functions with an _or_null suffix return NULL instead, which is usually what you want when indexing a column that may contain bad rows.

SELECT terra_latlon_to_cell_or_null(lat, lon, 8) FROM points;

R — Returns NA for individual failures within a vectorised call, and signals a condition for whole-call failures.

DuckDB — Returns NULL for row-level failures, consistent with its handling of other scalar functions.

Handling errors in bulk work

When indexing a large table, a single bad row should not abort the load. Prefer the null-returning variants, then count and inspect the nulls:

SELECT count(*) FILTER (WHERE cell IS NULL) AS failed,
       count(*)                             AS total
FROM indexed_points;

A small null count is usually bad source records. A large one is usually a systematic problem — transposed coordinates, wrong datum, or wrong column — and re-running the load without diagnosing it will produce a confidently wrong dataset.

Inspection — validating cells before use
SANSRS integration — datum errors and how to avoid them

The Terra System is designed and developed by Tec Solution KSA.

Error codes​

E_EXTENT — outside coverage​

E_CELL_INVALID — malformed cell​

E_CHECK_FAILED — bad grid code​

How each binding reports errors​

Handling errors in bulk work​

Next​