Error Codes

All API errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {}
  }
}

HTTP status codes

Status	Meaning
`200`	Success
`201`	Created
`204`	No content (successful deletion)
`400`	Bad request — invalid input
`401`	Unauthorized — missing or invalid auth
`403`	Forbidden — insufficient permissions
`404`	Not found
`409`	Conflict — resource already exists
`413`	Payload too large — file exceeds size limit
`422`	Unprocessable entity — validation failed
`429`	Too many requests — rate limited
`500`	Internal server error

Error codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid authentication
`FORBIDDEN`	403	Insufficient permissions for this action
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400/422	Request body failed validation
`DUPLICATE_ENTRY`	409	Resource with this identifier already exists
`FILE_TOO_LARGE`	413	Uploaded file exceeds maximum size
`UNSUPPORTED_FILE_TYPE`	400	File type is not supported
`RATE_LIMITED`	429	Too many requests — check `Retry-After` header
`PROCESSING_FAILED`	500	Document processing failed
`QUOTA_EXCEEDED`	403	Monthly document quota exceeded
`INTERNAL_ERROR`	500	Unexpected server error

Handling errors

Error handling example

const response = await fetch('https://api.dokubrain.com/api/v1/documents', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
 
if (!response.ok) {
  const { error } = await response.json();
 
  switch (error.code) {
    case 'UNAUTHORIZED':
      // Re-authenticate or refresh token
      break;
    case 'RATE_LIMITED':
      // Wait and retry
      const retryAfter = response.headers.get('Retry-After');
      break;
    case 'QUOTA_EXCEEDED':
      // Upgrade plan
      break;
    default:
      console.error(`API error: ${error.message}`);
  }
}

Rate limit headers

Rate-limited responses include these headers:

Header	Description
`X-RateLimit-Limit`	Max requests per window
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying

Error Codes

Error Codes

HTTP status codes

Error codes

Handling errors

Rate limit headers

On this page