Error Reference

This page documents the error codes and messages you may encounter when using IntuitivePM. Errors are grouped by HTTP status code. Each entry includes the error code, description, and recommended fix.

Understanding Error Responses

IntuitivePM returns errors in a consistent JSON format:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Project with ID 'abc-123' not found",
    "traceId": "d4e5f6a7-..."
  }
}

Field	Description
`success`	Always `false` for error responses
`error.code`	Machine-readable error code (e.g., `VALIDATION_ERROR`, `NOT_FOUND`)
`error.message`	Human-readable description of the error
`error.details`	Additional details (present for validation errors)
`error.traceId`	Unique identifier for this error. Include this when contacting support.

Client errors (4xx)

HTTP 400-429 errors indicate a problem with the request. These are typically fixable by the caller — check your input data, authentication, permissions, or rate limit usage.

HTTP 400 — Bad Request

Returned when the request contains invalid input data.

Error Code	Message	Fix
`VALIDATION_ERROR`	”Invalid input data”	Check the `details` field for specific field errors. Ensure required fields are present and values match expected types.
`VALIDATION_ERROR`	”Referenced record does not exist”	A foreign key reference points to a record that does not exist. Verify that referenced project, team, or user IDs are valid.
`PUBLIC_EMAIL_NOT_ALLOWED`	”Public email domains (Gmail, Yahoo, Outlook, etc.) are not allowed”	Register with a corporate email address. Public email providers cannot be used for account registration.

HTTP 401 — Unauthorized

Returned when authentication is missing or invalid.

Error Code	Message	Fix
`UNAUTHORIZED`	”Authentication required”	Your session has expired or no authentication token was provided. Log in again.
`UNAUTHORIZED`	”Invalid or expired token”	The JWT token is invalid. Clear your cookies and log in again.

HTTP 402 — Payment Required

Returned when a billing or credits issue prevents the request.

Error Code	Message	Fix
`INSUFFICIENT_CREDITS`	”Insufficient AI credits”	Your account does not have enough credits for this AI operation. Purchase additional credits in Settings > Billing or reduce usage. The response includes `available` and `required` credit amounts.
`USER_LIMIT_EXCEEDED`	”User limit exceeded for your plan”	Your workspace has reached the maximum number of users for your plan. Upgrade your plan or remove inactive members.

HTTP 403 — Forbidden

Returned when you are authenticated but lack permission for the requested action.

Error Code	Message	Fix
`FORBIDDEN`	”Insufficient permissions”	Your role does not have permission for this action. Contact your workspace admin to request the necessary role.
`FORBIDDEN`	”Only admins can update company settings”	Company settings require an admin or owner role. Ask your workspace owner to grant you admin access.
`FORBIDDEN`	”Only the owner can remove domains”	Domain removal is restricted to the workspace owner.
`FORBIDDEN`	”You are not a member of this company”	You are trying to access a workspace you do not belong to. Request an invitation from the workspace admin.

HTTP 404 — Not Found

Returned when the requested resource does not exist.

Error Code	Message	Fix
`NOT_FOUND`	”[Resource] with ID ‘[id]’ not found”	The resource (project, task, team, etc.) does not exist or has been deleted. Verify the ID is correct.
`NOT_FOUND`	”Record not found”	A database record referenced by the operation does not exist. This can happen if a record was deleted between loading a page and submitting a form. Refresh and try again.

HTTP 409 — Conflict

Returned when the request conflicts with the current state of a resource.

Error Code	Message	Fix
`CONFLICT`	”A record with this [field] already exists”	A unique constraint was violated. For example, two projects cannot have the same name within a company. Use a different value.
`CONFLICT`	”A record with this value already exists”	General duplicate record error. Check that you are not creating a duplicate entry.

HTTP 429 — Too Many Requests

Returned when you have exceeded the rate limit.

Error Code	Message	Fix
`RATE_LIMITED`	”Too many requests. Please try again later.”	Wait and retry after the time indicated in the `retryAfter` field (in seconds). AI endpoints have a burst limit of 3 requests per 60 seconds.

Server errors (5xx)

HTTP 500 errors indicate a problem on the server side. These are usually transient. Note the traceId from the error response and retry. If the error persists, contact support with the trace ID.

HTTP 500 — Internal Server Error

Returned when an unexpected error occurs on the server.

Error Code	Message	Fix
`INTERNAL_ERROR`	”An unexpected error occurred”	An unexpected server-side error. Note the `traceId` from the error response and report it to your administrator. In most cases, retrying the request will succeed.
`DATABASE_ERROR`	”Database operation failed”	A database operation failed unexpectedly. This is usually transient. Retry the request. If it persists, contact support with the trace ID.

Database Errors

SQLSTATE codes are internal only

PostgreSQL error codes (23505, 23503, etc.) are never exposed to API clients in production. They are mapped to standard HTTP status codes with safe error messages. The raw codes are logged server-side for debugging.

These errors originate from the database layer and are mapped to appropriate HTTP status codes. The internal PostgreSQL SQLSTATE codes are never exposed to clients in production.

HTTP Status	Internal Code	Client Message	Meaning
409	`23505` (unique_violation)	“A record with this value already exists”	Unique constraint violation. The value you are trying to insert already exists.
400	`23503` (foreign_key_violation)	“Referenced record does not exist”	Foreign key constraint violation. The referenced record was deleted or never existed.
404	—	“Record not found”	The record you are trying to update or delete does not exist.
500	Other SQLSTATE codes	”An unexpected error occurred”	An unexpected database error. The specific code is logged server-side for debugging.

Webhook Delivery Errors

These errors appear in webhook delivery logs when a webhook delivery fails.

Error	Meaning	Fix
`HTTP 400`	The receiving server rejected the payload	Check that your endpoint accepts the Adaptive Card or JSON format IntuitivePM sends.
`HTTP 401/403`	Authentication or authorization failure at the receiving end	Verify the webhook URL is still valid and has not been revoked.
`HTTP 404`	The endpoint URL is invalid or the resource was removed	Update the webhook URL to a valid endpoint.
`HTTP 500`	The receiving server encountered an error	Check the logs on your receiving server.
`Request timeout (30s)`	Your endpoint did not respond within 30 seconds	Optimize your endpoint to respond faster, or acknowledge the webhook and process asynchronously.
`Webhook URLs must use HTTPS in production`	HTTP URLs are blocked in production	Update the webhook URL to use HTTPS.
`Webhook URLs cannot point to localhost`	SSRF protection blocked a local URL	Use a publicly accessible URL for your webhook endpoint.

Virtual Colleague Errors

These errors appear in the Virtual Colleague activity log.

Error	Meaning	Fix
`Slack webhook URL is not configured`	No Slack webhook URL set for this colleague	Add a Slack webhook URL in the colleague’s Messaging settings.
`Teams webhook URL is not configured`	No Teams webhook URL set for this colleague	Add a Teams webhook URL in the colleague’s Messaging settings.
`Slack webhook returned [status]`	Slack rejected the message	Verify the webhook URL is valid and the Slack app is installed.
`Teams webhook returned [status]`	Teams rejected the message	Verify the webhook URL is valid and the Workflows connector is active.
`Could not resolve recipient email`	The target task has no assignee with an email address	Assign the task to a user with a valid email address.
`SMTP is not configured`	No SMTP settings for the company or system	Configure SMTP in Email Setup.

Getting Help

If you encounter an error not listed here or need additional assistance:

Note the traceId from the error response.
Check the Common Issues page for additional troubleshooting steps.
Contact your workspace administrator with the trace ID and a description of what you were doing when the error occurred.