Error Codes

Common API errors and how to resolve them.

HTTP Status Codes

Code	Meaning	Common Cause
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	API key lacks permission for this action
404	Not Found	Resource doesn't exist or wrong ID
409	Conflict	Resource already exists
422	Unprocessable	Valid syntax but semantic errors
429	Rate Limited	Too many requests
500	Server Error	Internal error - contact support

Error Response Format

{
  "errors": [{
    "code": "INVALID_TEMPLATE",
    "title": "Template Validation Failed",
    "detail": "Attribute 'email' missing required 'type' field"
  }]
}

Common Errors

Authentication Errors

401: Invalid API Key

{"errors": [{"code": "INVALID_API_KEY", "detail": "API key is invalid or expired"}]}

Fix:

1. Check key is copied correctly (no extra spaces)
2. Verify key hasn't been deleted in dashboard
3. Generate a new key if needed

403: Insufficient Permissions

{"errors": [{"code": "FORBIDDEN", "detail": "API key does not have access to this project"}]}

Fix: Use an API key created within the correct organization/project scope.

Template Errors

400: Invalid Template Schema

{"errors": [{"code": "INVALID_SCHEMA", "detail": "Attribute type must be one of: string, number, date, boolean"}]}

Fix: Check attribute types match allowed values.

409: Template Already Exists

{"errors": [{"code": "DUPLICATE", "detail": "Template with this name already exists"}]}

Fix: Use a unique template name or update the existing template.

Credential Errors

404: Credential Not Found

{"errors": [{"code": "NOT_FOUND", "detail": "Credential offer not found"}]}

Fix: Verify the credential/offer ID is correct and belongs to your project.

422: Invalid Credential Data

{"errors": [{"code": "VALIDATION_ERROR", "detail": "Required attribute 'employeeId' is missing"}]}

Fix: Include all required attributes defined in the template.

Rate Limiting

429: Too Many Requests

{"errors": [{"code": "RATE_LIMITED", "detail": "Rate limit exceeded. Retry after 60 seconds"}]}

Fix:

• Implement exponential backoff
• Check Retry-After header for wait time
• Consider batch operations for bulk actions

Troubleshooting Steps

1. Check the error code — Identifies the problem category
2. Read the detail message — Often tells you exactly what's wrong
3. Verify your request — Compare against API docs
4. Check resource IDs — Ensure orgId, projectId, templateId are correct
5. Test in Elements UI — Use Interactive Docs to validate

Getting Help

If errors persist:

• Check API Status
• Contact support with the full error response and request details