Troubleshooting

Quick-reference guide for diagnosing errors across all Solenoid APIs.

Error Lookup

Authentication Issues

My API key isn’t working

Diagnosis:

curl -I https://api.solenoid.systems/v1/meter/balance \
  -H "Authorization: Bearer sm_your_key_here"

Common causes:

• Typo in key (keys start with sm_)
• Wrong header format (must be Authorization: Bearer sm_...)
• Key was rotated or deleted
• Extra whitespace before or after the key

Resolution:

1. Verify key format: sm_ prefix, no whitespace
2. Verify header: Authorization: Bearer sm_... (space after Bearer)
3. Regenerate key via the dashboard if needed

OAuth token not accepted

Common causes:

• Token expired (access tokens expire after 1 hour)
• Token revoked by user or key rotation
• Using refresh token instead of access token
• Token missing required scopes

Resolution:

1. Refresh the token using your refresh token grant
2. Re-authenticate if the token was revoked
3. Verify token scopes match the endpoint requirements

Rate Limiting

I’m getting 429 errors

Rate limits by tier:

Check rate limit headers in any response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1709251200
Retry-After: 30

Resolution:

• Read the Retry-After header and wait before retrying
• Implement exponential backoff for retries
• Batch requests when possible
• Cache responses to avoid repeated fetches
• Upgrade your tier for higher limits

Balance Issues

Insufficient balance errors

Diagnosis:

curl https://api.solenoid.systems/v1/meter/balance \
  -H "Authorization: Bearer sm_your_key_here"

Common causes:

• All credits consumed
• Runaway process consuming credits unexpectedly
• Subscription expired or payment failed

Resolution:

1. Add credits via the dashboard or upgrade tier
2. Check logs for unusual spikes in API calls
3. Set up balance alerts to catch depletion early

Request Validation

Validation errors on requests

Validation errors return a fields object with specific issues:

{
  "error": "Validation failed",
  "code": "validation_error",
  "fields": {
    "amount": ["Expected number, received string"]
  }
}

Common fixes:

Permission Issues

Forbidden errors (403)

Common causes:

• Accessing another user’s resource
• OAuth token missing required scopes
• Feature not available on your tier
• Request from a blocked IP (if IP restrictions are configured)

Resolution:

1. Verify the resource ID belongs to your account
2. Re-authorize with correct scopes if using OAuth
3. Upgrade tier if accessing premium features
4. Check IP allowlist configuration

Resource Not Found

404 on resources that should exist

Diagnosis:

curl https://api.solenoid.systems/v1/meter/user-123/balance \
  -H "Authorization: Bearer sm_your_key_here"

Common causes:

• Typo or copy-paste error in the resource ID
• Resource was deleted by another process
• Looking in the wrong environment (production vs staging)
• Recently created resource not yet propagated (usually seconds)

Resolution:

1. Double-check the resource identifier
2. Wait and retry for recently created resources
3. Re-create the resource if it was deleted

Network Issues

Requests timing out

Diagnosis:

nslookup api.solenoid.systems
curl -v --connect-timeout 5 https://api.solenoid.systems/health

Resolution:

• Configure reliable DNS (1.1.1.1 or 8.8.8.8)
• Allow outbound HTTPS to api.solenoid.systems in firewall rules
• Configure HTTP_PROXY/HTTPS_PROXY if behind a proxy
• Increase client timeout for longer operations

SSL/TLS errors

Common causes:

• System clock is wrong (certificates validate against current time)
• Outdated root certificates (old OS or runtime)
• Corporate proxy with untrusted certificate
• Antivirus intercepting HTTPS

Resolution:

1. Sync system clock
2. Update OS or runtime for latest root certs
3. Add corporate CA to trust store if behind a proxy

Product-Specific Troubleshooting

For issues specific to individual products, see their dedicated error pages:

• Meter Errors
• Relay Errors
• Witness Errors
• Gate Errors
• Latch Errors
• Pulse Errors
• Catch Errors

Still Stuck?

1. Check status page — verify there’s no ongoing incident
2. Search docs — product-specific references may have your answer
3. Review API reference — ensure your request matches the spec
4. Contact support — include the request ID from response headers