Skip to main content

Documentation Index

Fetch the complete documentation index at: https://guide.promethex.market/llms.txt

Use this file to discover all available pages before exploring further.

​
Error Response Format

All errors follow the standard response envelope: 
{
  "code": 110101,
  "reason": "PARAM",
  "msg": "marketAddress is required",
  "data": null
}
​
code
number
Numeric error code. 0 means success. Non-zero indicates an error.
​
reason
string
Machine-readable error key. Use this for programmatic error handling.
​
msg
string
Human-readable error description. May vary — do not parse this for logic.

​
Client Errors (110100–110199)

Errors caused by invalid requests. Fix the request and retry.
CodeReasonDescriptionAction
110101PARAMMissing or invalid parameterCheck required fields, types, and formats
110102NOT_FOUNDRequested resource doesn’t existVerify the ID, address, or slug
110103PLEASE_WAITRate limitedBack off with exponential delay, then retry

​
Examples

{
  "code": 110101,
  "reason": "PARAM",
  "msg": "marketAddress is required",
  "data": null
}
Fix: Include the marketAddress field in your request.

​
Server Errors (110200–110299)

Internal server errors. These are typically transient — retry after a short delay.
CodeReasonDescriptionAction
110201INTERNALInternal server errorRetry; report if persistent
110202NETWORKNetwork connectivity issueRetry after a short delay
110203DATABASEDatabase errorRetry; report if persistent
110204REDISCache layer errorRetry; usually transient
110205RPCInternal gRPC call failedRetry; may indicate service degradation

​
Retry Strategy

async function apiCall(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(url, options);
    const json = await res.json();

    if (json.code === 0) return json.data;

    // Server errors — retry with backoff
    if (json.code >= 110200 && json.code < 110300) {
      const delay = Math.min(1000 * Math.pow(2, i), 10000);
      await new Promise(r => setTimeout(r, delay));
      continue;
    }

    // Client errors — don't retry
    throw new Error(`API Error ${json.code}: ${json.msg}`);
  }
  throw new Error('Max retries exceeded');
}

​
Third-Party Errors (110300–110399)

Errors from external services. Usually transient — retry after a delay.
CodeReasonDescriptionAction
110301S3File storage (S3) errorRetry the upload
110302ALCHEMYBlockchain RPC / bundler errorRetry; may be transient node issues
110303PRIVYAuthentication provider errorRefresh your JWT token and retry
110304OPENAIAI service errorRetry; non-critical feature

​
Handling Auth Errors

When you receive 110303 (PRIVY), your token may be expired or invalid: 
async function authenticatedFetch(url, options) {
  let res = await fetch(url, {
    ...options,
    headers: { ...options.headers, 'Authorization': `Bearer ${getToken()}` },
  });
  let json = await res.json();

  if (json.code === 110303) {
    // Token expired — refresh and retry
    await refreshPrivyToken();
    res = await fetch(url, {
      ...options,
      headers: { ...options.headers, 'Authorization': `Bearer ${getToken()}` },
    });
    json = await res.json();
  }

  return json;
}

​
HTTP Status Codes

The API also uses standard HTTP status codes alongside the custom error codes:
HTTP StatusMeaning
200Success (check code field for app-level errors)
400Bad request
401Unauthorized — missing or invalid JWT
403Forbidden — insufficient permissions
404Endpoint not found
429Rate limited
500Internal server error
Always check the code field in the response body, not just the HTTP status. A 200 response may contain an application-level error (non-zero code).

​
Error Code Quick Reference

RangeCategoryRetryableCommon Causes
110101–110103ClientNo (fix request)Bad params, missing resource, rate limit
110201–110205ServerYes (with backoff)Transient internal issues
110301–110304Third-partyYes (with backoff)External service outages