API Error Codes

Version: 1.0.0 Last Updated: 2025-01-XX Description: Complete catalog of API error codes for AI agents

Error Code Reference

HTTP Status Code Errors

Code Name Category Retryable Action Recovery
400 BAD_REQUEST client_error No Validate request parameters and format Check request body, headers, and parameter types
404 NOT_FOUND client_error No Verify resource ID and try again Check if resource ID is correct, or query list to find valid IDs
429 RATE_LIMIT_EXCEEDED rate_limit Yes Wait for retry_after seconds before retrying Implement rate limiting: reduce request frequency, use exponential backoff, respect Retry-After header
500 INTERNAL_SERVER_ERROR server_error Yes Retry with exponential backoff If error persists, report issue with request_id
503 SERVICE_UNAVAILABLE server_error Yes Wait for retry_after seconds, then retry Service may be under maintenance or overloaded

Consensus Network Error Codes

Code Name Category Retryable Action Recovery
0 SUCCESS success No Continue processing –
1 GENERAL_ERROR error Yes Log and retry with backoff Max 3 retries with exponential backoff
2 INSUFFICIENT_FUNDS error No Wait for resources Check player inventory, wait for resources to accumulate
3 INVALID_SIGNATURE error Yes Re-sign transaction Verify signature generation, re-sign with correct private key
4 INSUFFICIENT_GAS error Yes Increase gas limit Estimate gas requirements, increase gas limit in transaction
5 INVALID_MESSAGE error No Validate message format Check message structure against schema, verify all required fields
6 PLAYER_OFFLINE error No Restore capacity or shed load No halted field — online is (load+structsLoad) ≤ (capacity+secondary). Wire codespace is often 1152 (ErrPlayerOffline), not literal 6
7 INSUFFICIENT_CHARGE error No Wait for charge to accumulate Charge = height − gridAttributes.lastAction. Wire codespace often 1200
8 INVALID_LOCATION error No Validate location Check location format and validity
9 INVALID_TARGET error No Validate target Check target format and validity
1900 OBJECT_NOT_FOUND error No Verify resource ID Consensus Network returns 200 with error code, not 404. Check response.code field.

Network Errors

Code Name Category Retryable Action Recovery
timeout REQUEST_TIMEOUT network_error Yes Retry with exponential backoff Increase timeout duration or reduce request complexity
network NETWORK_ERROR network_error Yes Retry with exponential backoff Check network connectivity, verify server is running

Error Response Examples

400 BAD_REQUEST

{
  "error": "Bad request",
  "code": 400,
  "details": ["Invalid parameter format"]
}

404 NOT_FOUND

Affected endpoints: webapp-player-by-id, webapp-planet-by-id, webapp-guild-by-id, webapp-struct-by-id, player-by-id, planet-by-id, guild-by-id, struct-by-id

{
  "error": "Player not found",
  "code": 404,
  "details": ["Player ID 1-999 does not exist"]
}

429 RATE_LIMIT_EXCEEDED

{
  "error": "Rate limit exceeded",
  "code": 429,
  "retry_after": 60,
  "limit": 100,
  "remaining": 0,
  "reset_at": "2025-01-01T00:01:00Z"
}

500 INTERNAL_SERVER_ERROR

{
  "error": "Internal server error",
  "code": 500,
  "details": ["An unexpected error occurred"],
  "request_id": "req_1234567890"
}

503 SERVICE_UNAVAILABLE

{
  "error": "Service unavailable",
  "code": 503,
  "details": ["Service is temporarily unavailable"],
  "retry_after": 30
}

Consensus Network Errors (code 1-9, 1900)

Consensus Network errors are returned with HTTP 200 but with a non-zero code field in the response body.

{
  "code": 2,
  "message": "codespace structs code 2: insufficient funds",
  "details": []
}

{
  "code": 1152,
  "message": "codespace structs code 1152: player is offline",
  "details": []
}

Codes 1–9 in the table above are a simplified agent schema. Raw ABCI logs use module codespace IDs (e.g. offline 1152, insufficient charge 1200). There is no live player halted / code-6 halt path.

Error Categories

Category Description Codes
success Successful operations 0, 200
client_error Client-side errors (not retryable) 400, 404, 5, 6, 7, 8, 9, 1900
server_error Server-side errors (retryable) 500, 503
rate_limit Rate limiting errors (retryable with delay) 429
network_error Network-related errors (retryable) timeout, network
error Game-specific errors 1, 2, 3, 4

Retry Strategies

Exponential Backoff

Use for: server errors (500, 503), general errors (1), network errors

Fixed Delay

Use for: rate limit errors when Retry-After header is not provided

Respect Retry-After Header

Use for: rate limit errors (429) when Retry-After header is provided