Complete reference for Agent API error responses and how to handle them.
HTTP Status Codes
| Status | Meaning | Action |
|---|---|---|
| 200 | Success | Process response data |
| 400 | Bad Request | Check request format and parameters |
| 401 | Unauthorized | Check API key is valid and included |
| 404 | Not Found | Check resource ID exists |
| 429 | Rate Limited | Wait before retrying |
| 500 | Server Error | Retry later or contact support |
Registration Errors
Invalid Email Format
Status: 400
Response:
{
"error": "Invalid email format"
}
Cause: Email doesn't match valid email pattern
Solution: Validate email format before sending
Disposable Email
Status: 400
Response:
{
"error": "Disposable email addresses are not allowed"
}
Cause: Email is from a known disposable email domain
Solution: Use a permanent email address
Rate Limit Exceeded (Per Email)
Status: 429
Response:
{
"error": "Rate limit exceeded: max 1 request per email per 24 hours"
}
Cause: Same email was used in last 24 hours
Solution: Wait 24 hours or use different email
Rate Limit Exceeded (Per IP)
Status: 429
Response:
{
"error": "Rate limit exceeded: too many requests from this IP"
}
Cause: Too many requests from same IP address
Solution: Wait before retrying
Rate Limit Exceeded (Global)
Status: 429
Response:
{
"error": "Service temporarily unavailable, please try again later"
}
Cause: System-wide rate limit reached
Solution: Retry after a delay
Missing Required Field
Status: 400
Response:
{
"error": "operator_email is required"
}
Cause: Missing required field in request
Solution: Include all required fields
Status Check Errors
Registration Not Found
Status: 404
Response:
{
"error": "Registration not found"
}
Cause: Invalid or non-existent registration_id
Solution: Check registration_id is correct
Token Expired
Status: 200 (but status is "expired")
Response:
{
"status": "expired",
"message": "Registration token has expired"
}
Cause: Operator didn't approve within 24 hours
Solution: Create new registration
Registration Rejected
Status: 200 (but status is "rejected")
Response:
{
"status": "rejected",
"message": "Registration was declined by operator"
}
Cause: Operator clicked "Decline"
Solution: Contact operator or try different email
Form API Errors
Unauthorized (Missing API Key)
Status: 401
Response:
{
"error": "Unauthorized"
}
Cause: Missing or invalid Authorization header
Solution: Include Authorization: Bearer sr_live_xxx header
Invalid API Key
Status: 401
Response:
{
"error": "Unauthorized"
}
Cause: API key doesn't exist, expired, or inactive
Solution:
- Check key is correct
- Verify key hasn't expired
- Check if key was revoked
Form Not Found
Status: 404
Response:
{
"error": "Form not found"
}
Cause: User has no form (shouldn't happen, but possible)
Solution: Contact support
No Valid Fields to Update
Status: 400
Response:
{
"error": "No valid fields to update"
}
Cause: All fields in update request are protected or invalid
Solution: Include at least one valid, non-protected field
Verification Errors
Invalid Token
Status: 404
Response:
{
"error": "Invalid or expired token"
}
Cause: Token doesn't exist or is malformed
Solution: Use correct token from email
Token Expired
Status: 400
Response:
{
"error": "Token has expired"
}
Cause: Token older than 24 hours
Solution: Request new registration
Already Processed
Status: 400
Response:
{
"error": "Registration already processed",
"status": "approved"
}
Cause: Token was already used
Solution: Check status endpoint for current state
Turnstile Verification Failed
Status: 400
Response:
{
"error": "Verification failed. Please try again."
}
Cause: Turnstile challenge failed or missing
Solution: Complete Turnstile challenge on approval page
Password Too Short
Status: 400
Response:
{
"error": "Password is required and must be at least 8 characters"
}
Cause: Password less than 8 characters
Solution: Use password with 8+ characters
Error Handling Best Practices
Retry Logic
For transient errors (429, 500), implement exponential backoff:
async function retryWithBackoff(fn, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await fn();
} catch (error) {
if (error.status === 429 || error.status === 500) {
const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
await new Promise(resolve => setTimeout(resolve, delay));
continue;
}
throw error;
}
}
throw new Error("Max retries exceeded");
}
Validate Before Sending
Always validate inputs before API calls:
function validateEmail(email) {
return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}
if (!validateEmail(operatorEmail)) {
throw new Error("Invalid email format");
}
Handle All Status Values
When polling status, handle all possible values:
const status = response.status;
switch (status) {
case "pending_verification":
// Continue polling
break;
case "approved":
// Use API key and form URL
break;
case "rejected":
// Registration failed
break;
case "expired":
// Token expired, create new registration
break;
default:
// Unknown status
break;
}
Common Issues
API Key Not Working
Symptoms: 401 Unauthorized errors
Checklist:
- ✅ Key format:
sr_live_+ 64 hex characters - ✅ Authorization header:
Bearer sr_live_xxx - ✅ Key hasn't expired (90 days default)
- ✅ Key is active (not revoked)
Registration Stuck in Pending
Symptoms: Status stays "pending_verification" indefinitely
Possible Causes:
- Operator hasn't checked email
- Email went to spam
- Operator declined but status not updated yet
Solution: Wait reasonable time, then create new registration if needed
Form Updates Not Applying
Symptoms: PUT request succeeds but form doesn't change
Check:
- ✅ Fields are in allowed list (not protected)
- ✅ Color format is correct (6 hex chars, no #)
- ✅ Field values meet constraints (e.g., title length)