Skip to main content
This page covers the most common issues you may encounter when using ScreenScore AI and how to resolve each one. If you work through the steps here and the problem persists, reach out to support using the link at the bottom of this page.
This error means the API key is missing, malformed, or no longer valid.Steps to resolve:
  1. Confirm you are passing the key in the Authorization header using the Bearer scheme: 
    Authorization: Bearer YOUR_API_KEY
  2. Check that there are no extra spaces, line breaks, or truncation in the key value.
  3. Go to Settings → API Keys in the dashboard and verify the key is listed and has not been revoked. A revoked key shows a Revoked badge.
  4. If the key is missing or revoked, create a new one and update your integration.
This error means your account’s current plan does not include the feature you’re trying to use. For example, batch analysis is not available on the Free plan.Steps to resolve:
  1. Check the error response body for a message field explaining which feature is restricted.
  2. Review your current plan under Settings → Billing.
  3. Upgrade to a Pro or Enterprise plan to unlock the feature.
You have exceeded the rate limit for your plan. ScreenScore AI enforces per-minute request limits for all plans.
PlanRate limit
Free10 requests/min
Pro60 requests/min
Enterprise300 requests/min
Steps to resolve:
  1. Wait until the next minute window and retry your request.
  2. Check the Retry-After response header — it indicates how many seconds to wait before retrying.
  3. Implement exponential backoff in your client to handle rate limits gracefully: 
    async function requestWithBackoff(fn, retries = 4) {
  for (let i = 0; i < retries; i++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status !== 429 || i === retries - 1) throw err;
      await new Promise(r => setTimeout(r, 2 ** i * 1000));
    }
  }
}
  4. If you regularly hit the limit, consider upgrading your plan or batching requests during off-peak periods.
A failed status means ScreenScore AI could not process the submitted image.Common causes:
  • The image URL is not publicly accessible (for example, it requires authentication or is behind a firewall)
  • The image format is not supported (only JPEG, PNG, WebP, and SVG are accepted)
  • The file exceeds the 10 MB size limit
Steps to resolve:
  1. Check the error_message field in the analysis response for a specific reason: 
     curl https://api.screenscoreai.com/v1/analyses/ana_9k2mxp4q \
  -H "Authorization: Bearer YOUR_API_KEY"
  2. If the URL is not public, upload the image to a public storage bucket or use the file upload endpoint instead of a URL reference.
  3. Verify the file format and size before resubmitting.
  4. Once the issue is resolved, create a new analysis — failed analyses cannot be retried directly.
If your webhook endpoint is registered but not receiving event payloads, work through the following checks.Steps to resolve:
  1. Confirm your endpoint URL is publicly reachable from the internet. Localhost addresses and private network URLs won’t work.
  2. Verify your server is returning HTTP 200 within 10 seconds. Timeouts or non-200 responses cause ScreenScore AI to mark the delivery as failed.
  3. Check your server’s firewall and security group rules to ensure inbound HTTPS traffic on port 443 is permitted.
  4. Test the integration directly: go to Settings → Notifications → Webhooks, find your endpoint, and click Send Test Event. Check your server logs for the incoming request.
  5. Review delivery logs in the dashboard — each endpoint shows a history of recent delivery attempts and their response codes.
If the ScreenScore AI Figma plugin cannot connect to your account, the most likely cause is an incorrect or inactive API key in the plugin settings.Steps to resolve:
  1. Open the plugin settings panel inside Figma.
  2. Clear the current API key value and re-enter it carefully — avoid leading or trailing spaces.
  3. Go to Settings → API Keys in the ScreenScore AI dashboard and confirm the key you’re using is active and not revoked.
  4. If you don’t have an active key, create a new one, copy it immediately, and paste it into the plugin.
  5. Save the plugin settings and attempt to connect again.
Low scores can result from image quality issues rather than actual design problems.Steps to resolve:
  1. Check the resolution of your image. ScreenScore AI requires a minimum width of 800 pixels for reliable results — images below this threshold are harder to evaluate and tend to score lower.
  2. Try uploading the image at 2× resolution if your design tool supports exporting at higher density.
  3. Avoid heavily compressed JPEG exports — use PNG or WebP at high quality for more accurate scoring.
  4. If you have the Brand Consistency dimension enabled but haven’t configured a brand profile, the dimension will return 0 and drag down your overall score. Either set up a brand profile or disable that dimension in your scoring criteria.

Contact support

If you’ve worked through the steps above and are still experiencing issues, the support team is ready to help. Email support@screenscoreai.com with your account email, a description of the problem, and any relevant analysis IDs or error messages.