Error Codes & Handling

HTTP Status Codes

Status	Meaning	Common Causes
200	Success	Request completed successfully
201	Created	A resource was created
400	Bad Request	Invalid parameters or malformed request
401	Unauthorized	Missing or invalid API key
402	Payment Required	Insufficient quota for this operation
403	Forbidden	Valid auth but insufficient permissions
404	Not Found	Resource doesn’t exist
409	Conflict	The request conflicts with the current state, e.g. a duplicate name or a limit reached
412	Precondition Failed	The `If-Match` value no longer matches: the resource changed since you read it
422	Unprocessable Entity	The body or a parameter failed validation
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error
502	Bad Gateway	A service behind the API could not be reached; retry later
503	Service Unavailable	A dependency is temporarily unavailable; retry later

Error Response

When a request fails, the API returns a structured error body alongside the HTTP status code. The error_code field identifies the specific error for programmatic handling:

{
  "success": false,
  "message": "Human-readable error description",
  "error_code": "ERROR_CODE"
}

Every MemoryLake API endpoint answers errors in this format, including the refusals made before your request reaches the service: a missing or invalid API key (401), a key used from an address it is not allowed from (403), a rate limit (429), a service that cannot be reached (502) and maintenance (503). The inference endpoints of Memory Router are the one exception: they keep the provider’s format. When you contact support about a request, quote its X-Trace-ID response header.

Until October 2026, the refusals listed above used a different body, {"error": {"message", "type"}}. If your code reads error.message, read message and error_code instead.

What a 403 tells you

A permission refusal carries more than the code. Alongside error_code: ACCESS_DENIED, the data object names the permission that was missing and what would have satisfied it, so you can act on the response without guessing:

{
  "success": false,
  "message": "You don't have the \"Modify Library Item\" permission. Ask a team owner or admin to grant it.",
  "error_code": "ACCESS_DENIED",
  "data": {
    "denied": [
      {
        "permission": "drive:item_modify",
        "permission_level": "service",
        "resource_type": "drive"
      }
    ],
    "stage": "capability",
    "required_any_of": [
      { "key": "pkg:library:write", "resource_type": "library" }
    ]
  }
}

array

The permissions that were checked and not held. permission is the identifier to grant, permission_level says whether it is granted once for the whole service or per resource instance.

string

Which request to make of your admin. capability — ask for the permission itself; you do not have it anywhere, so widening your access to this one resource will not help. instance — ask for access to this resource; you already hold the permission elsewhere.

array

Any one of these grants would have allowed the request. Hand this to whoever administers your team: it is the shortest answer to “what do I need”.

A refusal does not tell you whether the resource exists — a 403 means “not for you” and says nothing more. Deletes work the same way: permission is checked first. Once it passes, deleting a resource that was already removed or was never there answers 200, so a repeated delete is safe to retry. If you could delete a resource only through a grant on that resource itself, rather than through your role, the grant is removed with the resource, so deleting it again answers 403. Deleting a knowledge entry that does not exist currently answers 400.

On team, member, invitation, API key, access-control, usage, billing and IM integration endpoints, a missing permission is answered with 403, ACCESS_DENIED and the message permission denied, without a data object; the permission each endpoint needs is listed on its page.

Refusals that protect an admin

Some changes would give someone an admin role, or take access away from an admin. Only the team owner or an admin can make them; anyone else gets 403 with ACCESS_DENIED, and data.operation names the change instead of a missing permission:

{
  "success": false,
  "message": "only an owner or admin may change an admin's role",
  "error_code": "ACCESS_DENIED",
  "data": { "operation": "change_role" }
}

operation is one of change_role, remove_member, remove_group_member, delete_group, reduce_admin_role_rules, narrow_admin_role_scope, narrow_admin_member_scope, downgrade_admin_member_tier, narrow_admin_via_group or remove_admin_member_rule. More values may be added.

Error Codes

Error Code	Description
`NOT_FOUND`	Resource not found
`DRIVE_ITEM_CONFLICT`	Drive item name conflict, e.g. file or folder with the same name already exists
`INVALID_ARGUMENT`	Invalid input: parameter validation, type mismatch, or malformed body
`CONNECTOR_NOT_LINKED`	Third-party connector (WPS, Lark, etc.) not yet authorized
`STATE_NOT_READY`	Resource exists but its current state does not allow the operation
`ACCESS_DENIED`	Caller lacks permission to access the resource
`QUOTA_EXCEEDED`	Quota or usage limit exceeded
`RATE_LIMIT_EXCEEDED`	Too many requests. Wait for the time in the `Retry-After` header before retrying. See Rate Limits
`SERVICE_UNAVAILABLE`	The service is temporarily unavailable, for example during maintenance. Retry later; `Retry-After` is sent when the wait is known
`DATASET_TABLE_LIMIT_EXCEEDED`	Number of tables in the NL2SQL dataset exceeds the allowed limit
`DB_CONNECTION_FAILED`	Could not connect to the database with the connection settings provided: the host is unreachable, the credentials were rejected, or the database does not exist. Retrying with the same settings will not help
`RESOURCE_LIMIT_EXCEEDED`	A count limit configured for your account was exceeded, for example the number of projects in a workspace or the number of `project_ids` in one request
`DOWNLOAD_NOT_SUPPORTED`	The requested resource does not support download
`UNAUTHORIZE`	Authentication required
`CONNECTOR_UNAUTHORIZE`	Connector unauthorized
`CUSTOM_ID_CONFLICT`	A resource with the given `custom_id` already exists
`BINDING_ALREADY_EXISTS`	The binding relationship already exists
`RESOURCE_IN_USE`	The resource is still referenced by others and cannot be deleted until they are, for example a database connection that still has datasources, or an analysis model still bound to a database memory
`SKILL_NAME_CONFLICT`	A skill with the given `name` already exists in your tenant
`SKILL_NOT_USABLE`	An agent or agent version referenced a skill that has not passed security review, does not exist, or has no package yet
`ACTOR_INACTIVE`	The actor or agent has been deleted. It is still listed in the workspace and its memories stay readable, but it can no longer take part in writes
`AGENT_OPERATION_NOT_SUPPORTED`	The operation needs an agent whose runtime MemoryLake hosts: versions, forking and A2A are only available for `INTERNAL` agents, not `EXTERNAL` ones. Unlike `STATE_NOT_READY`, retrying will not help
`TENANT_CREATION_LIMIT_REACHED`	The key’s owner already has as many teams as they may create
`ORG_TENANT_CREATION_DISABLED`	Creating teams is not available on this deployment
`INTERNAL_ERROR`	Unexpected server-side error

Error Handling Best Practices

Retry Logic

async function apiRequest(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      
      if (response.ok) {
        return await response.json();
      }
      
      // Don't retry 4xx errors (except 429)
      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
        throw new Error(`Client error: ${response.status}`);
      }
      
      // Exponential backoff for 5xx and 429
      if (i < maxRetries - 1) {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

Error Logging

try {
  const data = await apiRequest(url, options);
  return data;
} catch (error) {
  console.error('API Error:', {
    url,
    status: error.status,
    message: error.message,
    timestamp: new Date().toISOString()
  });
  throw error;
}

MemoryLake API

Memory Router API

HTTP Status Codes

Error Response

What a 403 tells you

Refusals that protect an admin

Error Codes

Error Handling Best Practices

Retry Logic

Error Logging

Next Steps

Authentication

Rate Limits

​HTTP Status Codes

​Error Response

​What a 403 tells you

​Refusals that protect an admin

​Error Codes

​Error Handling Best Practices

​Retry Logic

​Error Logging

​Next Steps

Authentication

Rate Limits

HTTP Status Codes

Error Response

What a 403 tells you

Refusals that protect an admin

Error Codes

Error Handling Best Practices

Retry Logic

Error Logging

Next Steps