Errors and rate limits

Most yggy API error responses include a machine-readable code alongside a human-readable message:

{
  "success": false,
  "error": {
    "message": "A provider with this name already exists for this type.",
    "code": "PROVIDER_CONFLICT"
  }
}

A few refusals answer with a flat body instead, such as { "error": "Authentication required" }, so check the status code first.

Use code for program logic. Treat it as part of the versioned API contract. You can show message to users, but do not use its text for program logic.

The Reference lists the error responses of every operation.

Rate limits

Each personal or organization API key can make 5000 requests per hour.

When a personal or organization key exceeds its hourly request cap, the status is 429 (not 401), error.code is RATE_LIMITED, and Retry-After is the wait in seconds.

Wait at least Retry-After seconds before you send the next request with that key. To follow a document through processing, prefer GET /api/v1/documents/{id}/status/stream over tight polling, so the stream does not spend the quota.

Request logs

When a call fails, look it up by its request ID in Developers → Usage and logs. Request logs explains what the log holds and who sees it, and Export logs over OTLP how to stream it to your own log tool.

Codes

Code	Meaning
`INTERNAL_ERROR`	An unexpected server error occurred.
`VALIDATION_ERROR`	The request failed validation.
`UNAUTHORIZED`	Authentication is required or has expired.
`RATE_LIMITED`	The API key exceeded its request rate limit. Wait and retry.
`ORG_REQUIRED`	An active organization context is required.
`FORBIDDEN`	The caller does not have permission to perform this action.
`NOT_FOUND`	The requested resource could not be found.
`CONFLICT`	The request conflicts with the current state of the resource.
`PROJECT_DENIED`	The caller does not have access to this project.
`USAGE_LIMIT_EXCEEDED`	This organization reached its usage limit for this period. Upgrade to Pro to add a payment method and keep working.
`HUGINN_ERROR`	The chat agent failed to process the request.
`HUGINN_STREAM_ERROR`	The chat response stream failed.
`QUERY_FAILED`	The graph query could not be completed.
`PROVIDER_CONFLICT`	A provider with this name already exists for this type.
`PROVIDER_CONFIG_INVALID`	The provider configuration failed validation.
`PROVIDER_NOT_CONNECTED`	This provider is not connected.
`PROVIDER_RATE_LIMITED`	The connected provider is rate limiting requests. Wait and retry.
`PROJECT_MEMBER_USER_NOT_IN_ORG`	The user is not a member of this organization.
`PROJECT_MEMBER_UNKNOWN_ROLE`	The given role is not defined for this organization.
`PROJECT_MEMBER_LAST_OWNER`	Cannot remove or demote the last owner of a project.
`PROJECT_CONFLICT`	A project with this slug already exists for this organization.
`STORAGE_NOT_CONFIGURED`	File storage is not configured for this deployment.
`BILLING_NOT_CONFIGURED`	Billing is not configured for this deployment.
`LICENSE_INACTIVE`	This installation has no active license, so it is read-only. An administrator can upload a new license under Settings > License.
`PLAN_REQUIRED`	This feature requires a higher organization plan.
`MEMBER_LIMIT_REACHED`	The organization has reached its member limit for the current plan.
`SAGA_ASK_QUOTA_EXCEEDED`	The Saga Ask quota for this period has been exceeded.
`SAGA_ASK_RATE_LIMITED`	Too many Ask requests. Try again shortly.
`SAGA_ASK_BUSY`	Another Ask is still answering. Wait for it to finish.
`SAGA_ASK_PAUSED`	Ask is paused for Free accounts until tomorrow.
`SAGA_ASK_UPSTREAM`	The Ask service is temporarily unavailable.
`SAGA_DICTATION_BUSY`	Speech to text is busy. Retry after the delay in the Retry-After header.
`SAGA_DICTATION_UNAVAILABLE`	Speech to text is temporarily unavailable.
`SAGA_SHARE_LINK_LIMIT`	The Free plan allows 3 public links at a time. Turn one off or upgrade to Plus.
`PROJECT_MEMBERSHIP_JWT_TOO_LARGE`	This organization has too many projects to open in one session. Contact support so we can raise the limit.
`WEBHOOK_URL_INVALID`	The webhook URL must be a valid HTTPS URL without credentials.
`WEBHOOK_ADDRESS_BLOCKED`	yggy cannot send webhooks to this URL.
`WEBHOOK_EVENT_UNKNOWN`	A webhook subscription names an event that is not in the event catalog.
`WEBHOOK_ENDPOINT_LIMIT`	The organization already has the maximum number of webhook endpoints.
`WEBHOOK_ENDPOINT_DISABLED`	The webhook endpoint is disabled. Enable it first.
`WEBHOOK_DELIVERY_IN_PROGRESS`	The delivery is still being sent. Redeliver it once it has finished.
`ORG_KEY_PERSONAL_SCOPE`	Organization API keys act as the organization and cannot use routes that work on a person's own data. Use a personal key.
`API_KEY_PERMISSION_EXCEEDS_ROLE`	The key asks for a permission that your role does not have.
`API_KEY_NO_PERMISSIONS`	This organization API key holds no permissions, so it cannot do anything.
`ORG_KEY_GRAPH_SCOPE_UNAVAILABLE`	Organization API keys are unavailable because graph access cannot be scoped. Try again later.
`ORG_KEY_TOO_MANY_PROJECTS`	This organization has more shared projects than one organization API key can reach. Limit the key to one project.
`SENDER_IS_LOGIN_EMAIL`	This address is already used to sign in.
`SENDER_TAKEN`	Another person already uses this address as a sender.