Error Codes

Complete reference of error codes returned by the Sazabi API.

HTTP Status Codes

Error Response Format

All errors return a consistent JSON structure:

{
  "data": null,
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or expired.",
    "doc_url": "https://sazabi.com/docs/developer/api/errors#invalid_api_key"
  }
}

Error Codes

Authentication Errors

These errors occur when there is a problem with your API key or authentication.

invalid_api_key

The API key provided is not valid. This can happen if:

• The key was copied incorrectly
• The key format is invalid (should start with pk_ or sk_)
• The key does not exist

Example error:

{
  "data": null,
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or expired."
  }
}

Resolution:

1. Verify you are using the correct key from the dashboard
2. Check that the key starts with pk_ (public) or sk_ (secret)
3. Ensure the key has not been deleted

expired_api_key

The API key was valid but has been revoked or expired.

Resolution:

1. Go to Settings > API Keys in the dashboard
2. Create a new API key
3. Update your application with the new key

missing_api_key

No API key was provided in the request headers.

Resolution:

Include the appropriate header:

# For public keys (intake endpoints)
-H "x-sazabi-key: pk_live_your_public_key"

# For secret keys (API endpoints)
-H "x-sazabi-secret-key: sk_live_your_secret_key"

Permission Errors

These errors occur when your API key does not have access to the requested resource.

insufficient_permissions

The API key does not have the required permissions for this operation.

Example: Using a public key (pk_) to access the threads API, which requires a secret key (sk_).

Resolution:

• For read/write API operations, use a secret key
• For data ingestion, use a public key

project_access_denied

The API key does not have access to the specified project. Public keys are scoped to a single project.

Resolution:

1. Verify you are using a key created for this project
2. For cross-project access, use a secret key (organization-scoped)

Rate Limiting

These errors occur when you exceed the API rate limits.

rate_limit_exceeded

You have exceeded the rate limit for this API key.

Example error:

{
  "data": null,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 60 seconds."
  }
}

Response headers:

Resolution:

1. Implement exponential backoff in your client
2. Cache responses where possible
3. Batch requests when the API supports it
4. Contact support if you need higher limits

Validation Errors

These errors occur when request parameters are invalid.

invalid_parameter

A parameter value does not match the expected format or constraints.

Example error:

{
  "data": null,
  "error": {
    "code": "invalid_parameter",
    "message": "Parameter 'limit' must be between 1 and 100"
  }
}

Resolution:

Check the API documentation for valid parameter values and formats.

missing_parameter

A required parameter was not included in the request.

Example error:

{
  "data": null,
  "error": {
    "code": "missing_parameter",
    "message": "Parameter 'content' is required"
  }
}

Resolution:

Include all required parameters as specified in the endpoint documentation.

invalid_json

The request body could not be parsed as valid JSON.

Resolution:

1. Validate your JSON using a tool like jq
2. Ensure proper escaping of special characters
3. Check for trailing commas or missing quotes

Resource Errors

These errors occur when the requested resource cannot be found or accessed.

not_found

The requested resource does not exist or has been deleted.

Example error:

{
  "data": null,
  "error": {
    "code": "not_found",
    "message": "Thread 'thr_abc123' not found"
  }
}

Resolution:

1. Verify the resource ID is correct
2. Check that the resource has not been deleted
3. Ensure you have access to this resource

Server Errors

These errors indicate a problem on the server side.

internal_error

An unexpected error occurred on the server.

Resolution:

1. Retry the request with exponential backoff
2. If the error persists, contact support with the request ID

Handling Errors

Recommended error handling

async function fetchWithRetry(url: string, options: RequestInit) {
  const maxRetries = 3;
  let lastError: Error;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      const data = await response.json();

      if (data.error) {
        // Handle specific error codes
        switch (data.error.code) {
          case "rate_limit_exceeded":
            // Wait and retry
            const retryAfter = response.headers.get("Retry-After") || "60";
            await sleep(parseInt(retryAfter) * 1000);
            continue;

          case "invalid_api_key":
          case "expired_api_key":
            // Don't retry auth errors
            throw new Error(`Authentication failed: ${data.error.message}`);

          case "internal_error":
            // Retry with backoff
            await sleep(Math.pow(2, attempt) * 1000);
            continue;

          default:
            throw new Error(data.error.message);
        }
      }

      return data;
    } catch (error) {
      lastError = error as Error;
    }
  }

  throw lastError!;
}

Best practices

1. Always check for errors in the response body, not just HTTP status codes
2. Implement exponential backoff for transient errors (429, 500, 503)
3. Log error codes for debugging and monitoring
4. Do not retry authentication or validation errors
5. Include request IDs when contacting support

Next steps