Error Reference

Response Format

When an API request fails, the response includes result: false and an errors array:

{
  "result": false,
  "errors": [
    {
      "code": 97,
      "message": "Insufficient balance"
    }
  ]
}

All API responses return HTTP 200. Use the result field and error code to determine success or failure.

Error Codes

Error codes indicate the category of the problem. Use these for conditional logic in your application.

Authentication Errors

Returned when API key or bearer token authentication fails. All return HTTP 401.

Signature Auth Errors

If your project uses signature-based authentication, ensure all three headers are present and the signature is computed correctly:

x-api-key: YOUR_API_KEY
x-signature: HMAC-SHA256(key=API_KEY, message=API_SECRET + NONCE)
x-nonce: Unix timestamp or random integer

See Authentication for details.

IP Whitelist Errors

If your project has an IP whitelist configured, requests from unlisted IPs will be rejected. Use * in the whitelist to allow all IPs.

Team API Key Errors

A team project's API key works only while the user who created the project is an active member of the team or the organization owner. Once they leave the team, requests with the key fail with "The person who created this API key is no longer in its team." Public endpoints such as Tool/List and Agent/List still answer, as if the request had no key. Switch to a key from a project that an active member created.

Creating, changing, deleting or restoring organizations and teams, managing members and invitations, and moving projects, agents or credit need a signed-in user, in the dashboard or with a Bearer token. With an API key, these calls fail with "API keys can't manage teams or organizations." See Team API Access.

Studio and the Workflow Agent are stricter: the user who created the key's project must be an active member of the team, and being the organization owner is not enough. When that user is the organization owner but not a member of the team, requests to them fail with HTTP 403:

Run Errors

Returned by POST /Run/{owner}/{model}.

Balance & Limits

Validation Errors

Model Access Errors

Training Model Errors

Task Errors

Returned by POST /Task/Detail, POST /Task/Cancel, POST /Task/Kill, and POST /Task/InputOutputDelete.

Error Handling

Always check result first, then inspect the code in the errors array:

const data = await response.json();

if (!data.result) {
  const error = data.errors[0];
  switch (error.code) {
    case 96:
      console.log('Concurrent limit — wait for a task to finish');
      break;
    case 97:
      console.log('Insufficient balance — add funds');
      break;
    case 98:
      console.log('Sign in required');
      break;
    default:
      console.log('Error:', error.message);
  }
}

Retry Strategy