Docs/Error Codes

Error Codes

Understanding API errors and how to handle them in your application.

Error Response Format

All API errors return a JSON object with the following structure:

{
  "error": "error_code",
  "message": "Human-readable error description",
  "details": { ... },  // Optional additional context
  "requestId": "req_xxx"  // For support reference
}

Always check the error field for programmatic error handling, not the HTTP status code alone.

HTTP Status Codes

400Bad Request

The request was malformed or missing required parameters.

Common Causes:

•Missing required fields in request body
•Invalid JSON syntax
•Invalid parameter values

Solution:

Check your request body and parameters match the API specification.

401Unauthorized

Authentication failed or was not provided.

Common Causes:

•Missing Authorization header
•Invalid or expired API key
•API key lacks required permissions

Solution:

Ensure you're including a valid API key in the Authorization header.

403Forbidden

You don't have permission to access this resource.

Common Causes:

•Trying to access another user's private resource
•API key doesn't have the required scope
•Account suspended or restricted

Solution:

Verify you have the correct permissions for this operation.

404Not Found

The requested resource doesn't exist.

Common Causes:

•Skill name is incorrect or doesn't exist
•User or organization not found
•Resource was deleted

Solution:

Verify the resource identifier is correct.

409Conflict

The request conflicts with the current state of the resource.

Common Causes:

•Skill name already exists
•Version number already published
•Concurrent modification detected

Solution:

Change the conflicting value or wait and retry.

422Unprocessable Entity

The request was valid but the data failed validation.

Common Causes:

•Skill content failed security scan
•Invalid skill manifest format
•Required metadata missing from SKILL.md

Solution:

Check the error details for specific validation failures.

429Too Many Requests

You've exceeded the rate limit for your plan.

Common Causes:

•Too many requests in a short period
•Rate limit varies by plan (free: 60/min, pro: 300/min)

Solution:

Wait for the rate limit window to reset, or upgrade your plan.

500Internal Server Error

An unexpected error occurred on our servers.

Common Causes:

•Temporary server issue
•Database error
•Internal service failure

Solution:

Retry the request. If it persists, contact support.

503Service Unavailable

The service is temporarily unavailable.

Common Causes:

•Planned maintenance
•High load causing temporary unavailability
•Dependent service outage

Solution:

Check the status page and retry after a few minutes.

Specific Error Codes

These are the specific error codes you may encounter in the error field.

skill_not_found404

The requested skill does not exist or has been deleted.

{ "error": "skill_not_found", "message": "Skill '@username/my-skill' not found" }

skill_name_taken409

A skill with this name already exists in your account.

{ "error": "skill_name_taken", "message": "Skill name 'my-skill' is already taken" }

version_exists409

This version has already been published.

{ "error": "version_exists", "message": "Version 1.0.0 already exists" }

invalid_manifest422

The SKILL.md file has an invalid or missing manifest.

{ "error": "invalid_manifest", "message": "Missing required field: description" }

security_scan_failed422

The skill failed security scanning with a score below 50.

{ "error": "security_scan_failed", "message": "Security score 35 is below minimum (50)", "score": 35, "issues": [...] }

typosquatting_detected400

The skill name is too similar to an existing popular skill.

{ "error": "typosquatting_detected", "message": "Skill name 'reviewing-c0de' is too similar to existing skills: 'reviewing-code' (95% similar)" }

reserved_name400

The skill name contains a reserved word that cannot be used.

{ "error": "reserved_name", "message": "Name cannot contain 'openai' - this word is reserved to prevent impersonation" }

rate_limit_exceeded429

You've exceeded your rate limit.

{ "error": "rate_limit_exceeded", "message": "Rate limit exceeded. Resets in 45 seconds", "retryAfter": 45 }

invalid_api_key401

The provided API key is invalid or expired.

{ "error": "invalid_api_key", "message": "Invalid or expired API key" }

missing_api_key401

No API key was provided for an authenticated endpoint.

{ "error": "missing_api_key", "message": "API key required for this endpoint" }

insufficient_permissions403

Your API key doesn't have the required permissions.

{ "error": "insufficient_permissions", "message": "This API key cannot publish skills" }

plan_limit_exceeded403

You've exceeded a limit of your current plan.

{ "error": "plan_limit_exceeded", "message": "Free plan limited to 5 skills. Upgrade to Pro for unlimited." }

execution_timeout408

The skill execution timed out.

{ "error": "execution_timeout", "message": "Execution timed out after 30 seconds" }

execution_error500

An error occurred during skill execution.

{ "error": "execution_error", "message": "Runtime error: undefined is not a function" }

review_duplicate409

You've already reviewed this skill.

{ "error": "review_duplicate", "message": "You have already reviewed this skill" }

self_review403

You cannot review your own skill.

{ "error": "self_review", "message": "You cannot review your own skill" }

webhook_delivery_failed502

Failed to deliver webhook to your endpoint.

{ "error": "webhook_delivery_failed", "message": "Endpoint returned 500", "attempts": 3 }

Error Handling Best Practices

1. Always check the error code

const response = await fetch('/api/v1/skills');
const data = await response.json();

if (!response.ok) {
  switch (data.error) {
    case 'rate_limit_exceeded':
      // Wait and retry
      await sleep(data.retryAfter * 1000);
      return retry();
    case 'invalid_api_key':
      // Refresh token or re-authenticate
      return refreshAuth();
    default:
      throw new Error(data.message);
  }
}

2. Implement exponential backoff for rate limits

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
      await sleep(retryAfter * 1000);
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

3. Log request IDs for debugging

if (!response.ok) {
  const data = await response.json();
  console.error('API Error:', {
    error: data.error,
    message: data.message,
    requestId: data.requestId, // Include this in support tickets
  });
}

Getting Help

If you encounter an error you can't resolve:

Check the status page for ongoing incidents
Search the documentation for the specific error
Include the requestId when contacting support
Contact support@joinasterism.com

← SDKs API Reference →