Reference guide for API error codes and how to handle them.
All API errors follow a consistent JSON format:
{
"error": {
"code": "AUTH_TOKEN_EXPIRED",
"message": "Token has expired",
"status": 401,
"details": {
"expiredAt": "2024-01-15T10:30:00Z"
},
"requestId": "req_abc123xyz"
}
}Machine-readable error identifier. Use this for programmatic error handling.
Human-readable error description. Safe to display to users.
Additional context about the error. Structure varies by error type.
Unique request identifier. Include this when contacting support.
AUTH_TOKEN_MISSINGAuthentication required
No authentication token was provided in the request.
Include a valid Bearer token in the Authorization header or an API key in the X-API-Key header.
AUTH_TOKEN_INVALIDInvalid authentication token
The provided token is malformed or has been tampered with.
Obtain a new token by authenticating again. Ensure the token is copied correctly.
AUTH_TOKEN_EXPIREDToken has expired
The authentication token has exceeded its validity period.
Refresh your token using the refresh token endpoint or authenticate again.
AUTH_API_KEY_INVALIDInvalid API key
The provided API key does not exist or has been revoked.
Check that your API key is correct. Generate a new key if needed.
FORBIDDENAccess forbidden
You do not have permission to access this resource.
Verify your account has the required permissions or contact an administrator.
SCOPE_INSUFFICIENTInsufficient scope
Your API key does not have the required scope for this operation.
Create a new API key with the required scopes or use a token with broader permissions.
ORGANIZATION_ACCESS_DENIEDOrganization access denied
You are not a member of this organization.
Request access to the organization from an administrator.
RESOURCE_NOT_FOUNDResource not found
The requested resource does not exist.
Verify the resource ID is correct. The resource may have been deleted.
USER_NOT_FOUNDUser not found
No user exists with the specified identifier.
Check the user ID or email. The user may not have registered.
CONVERSATION_NOT_FOUNDConversation not found
The specified conversation does not exist.
Verify the conversation ID. Create a new conversation if needed.
KNOWLEDGE_BASE_NOT_FOUNDKnowledge base not found
The specified knowledge base does not exist.
Check the knowledge base ID. It may have been deleted.
VALIDATION_ERRORValidation failed
The request body failed validation.
Check the error details for specific field validation failures.
INVALID_JSONInvalid JSON
The request body is not valid JSON.
Ensure your request body is properly formatted JSON.
MISSING_REQUIRED_FIELDMissing required field
A required field is missing from the request.
Include all required fields in your request body.
INVALID_FIELD_TYPEInvalid field type
A field has an incorrect data type.
Ensure field types match the API specification (string, number, boolean, etc.).
RATE_LIMIT_EXCEEDEDRate limit exceeded
You have made too many requests in a short period.
Wait before making more requests. Check the Retry-After header for timing.
QUOTA_EXCEEDEDQuota exceeded
You have exceeded your API usage quota for the billing period.
Upgrade your plan or wait for the quota to reset.
RESOURCE_ALREADY_EXISTSResource already exists
A resource with the same identifier already exists.
Use a different identifier or update the existing resource.
EMAIL_ALREADY_REGISTEREDEmail already registered
An account with this email already exists.
Use a different email or sign in to the existing account.
CONCURRENT_MODIFICATIONConcurrent modification
The resource was modified by another request.
Fetch the latest version and retry your update.
INTERNAL_SERVER_ERRORInternal server error
An unexpected error occurred on the server.
Retry the request. If the problem persists, contact support.
SERVICE_UNAVAILABLEService unavailable
The service is temporarily unavailable.
Wait and retry. Check our status page for updates.
AI_PROVIDER_ERRORAI provider error
The AI provider returned an error.
Retry the request. The AI provider may be experiencing issues.
Use the code field for programmatic error handling:
try {
const response = await oneapp.ai.messages.create({...});
} catch (error) {
switch (error.code) {
case 'AUTH_TOKEN_EXPIRED':
await refreshToken();
// Retry the request
break;
case 'RATE_LIMIT_EXCEEDED':
const retryAfter = error.details?.retryAfter ?? 60;
await sleep(retryAfter * 1000);
// Retry the request
break;
default:
console.error('Unexpected error:', error.message);
}
}For rate limits and transient errors (429, 500, 502, 503), retry with exponential backoff. Start with 1 second and double the delay after each retry, up to a maximum.
Always log the requestId from error responses. This helps our support team quickly identify and resolve issues.