Troubleshooting

Solutions to common issues when working with the CORTEX API.

Authentication Issues

"Invalid or expired access token"

Cause: The access token has expired or is malformed.

Solution:

1. Check if the token has expired (15-minute lifetime)
2. Use the refresh token to get a new access token
3. If refresh fails, log in again

if (response.status === 401) {
  try {
    await refreshTokens();
    // Retry request
  } catch {
    // Redirect to login
  }
}

"Account is temporarily locked"

Cause: Too many failed login attempts (5 within 15 minutes).

Solution:

1. Wait 15 minutes for the lockout to expire
2. Ensure you're using the correct password
3. Contact admin if you've forgotten your password

"The email or password provided is incorrect"

Cause: Invalid credentials.

Solution:

1. Verify the email address is correct
2. Check for typos in the password
3. Ensure Caps Lock is not on
4. Use password reset if necessary

Permission Issues

"You do not have permission to perform this action"

Cause: Your role doesn't include the required permission.

Solution:

1. Check your current roles: GET /auth/me
2. Request the necessary role from your administrator
3. Verify you're in the correct organization context

"Required permission: users:create"

Cause: Specific permission is missing.

Solution:

1. Identify the required permission from the error
2. Check if your role should have this permission
3. Contact admin to grant the permission

Resource Issues

"The requested resource was not found" (404)

Causes:

• Resource doesn't exist
• Resource is in a different tenant
• Resource is in a different organization (and you don't have access)

Solution:

1. Verify the resource ID is correct
2. Check you're authenticated as the correct user
3. Verify you have access to the organization containing the resource

"A user with this email already exists" (409)

Cause: Attempting to create a duplicate resource.

Solution:

1. Check if the user already exists
2. Use a different email address
3. If the existing user should be updated, use PATCH instead

Validation Issues

"One or more fields failed validation"

Cause: Request body contains invalid data.

Solution:

1. Check the errors array in the response
2. Fix each validation error
3. Ensure all required fields are present

{
  "errors": [
    { "field": "email", "message": "must be a valid email" },
    { "field": "password", "message": "must be at least 8 characters" }
  ]
}

"Password must contain at least one..."

Cause: Password doesn't meet policy requirements.

Solution: Ensure password contains:

• Minimum 8 characters
• At least 1 uppercase letter (A-Z)
• At least 1 lowercase letter (a-z)
• At least 1 number (0-9)
• At least 1 special character (!@#$%^&*)

Rate Limiting

"Rate limit exceeded. Try again in X seconds"

Cause: Too many requests in a short time period.

Solution:

1. Check the Retry-After header or retryAfter field
2. Wait the specified time before retrying
3. Implement exponential backoff
4. Consider caching responses

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        const delay = error.details.retryAfter * 1000 || 1000 * Math.pow(2, i);
        await sleep(delay);
      } else {
        throw error;
      }
    }
  }
  throw new Error('Max retries exceeded');
}

Connection Issues

"Service Unavailable" (503)

Cause: Server is temporarily unavailable.

Solution:

1. Wait a few seconds and retry
2. Check the status page
3. Contact support if the issue persists

Network Errors

Cause: Network connectivity issues.

Solution:

1. Check your internet connection
2. Verify the API URL is correct
3. Check if a firewall is blocking requests
4. Ensure CORS is configured correctly

Debugging Tips

Enable Request Logging

async function apiCall(url, options) {
  console.log('Request:', { url, ...options });

  const response = await fetch(url, options);
  const data = await response.json();

  console.log('Response:', { status: response.status, data });

  return data;
}

Check Request Headers

Ensure your requests include:

Content-Type: application/json
Authorization: Bearer <token>

Verify Token Payload

Decode your JWT to check its contents:

function decodeToken(token) {
  const payload = token.split('.')[1];
  return JSON.parse(atob(payload));
}

const payload = decodeToken(accessToken);
console.log('Token expires:', new Date(payload.exp * 1000));
console.log('Tenant:', payload.tenantId);

Getting Help

If you're still stuck:

1. Check the API Reference
2. Review the error code in Error Codes
3. Contact support with:
   • The full error response
   • The request that caused it
   • Your user ID and tenant ID