Errors

Every error response has the same shape, a stable machine-readable code and a fitting HTTP status. Branch on the code; show the message to people.

Error envelope#

422 Unprocessable Entity

{
  "error": {
    "code": "validation_failed",
    "message": "Some fields need attention.",
    "details": {
      "email": "Enter a valid email address.",
      "password": "Use at least 10 characters."
    }
  }
}

code is stable; build logic on it.
message is a sentence written for people. It may change, so don't parse it.
details appears with validation_failed only, keyed by request field.
The X-Request-Id response header names the request in the API's logs. Quote it when you report a problem.

Error codes#

Code	Status	Meaning
`validation_failed`	422	One or more fields are invalid. `details` maps each field to a message.
`invalid_json`	400	The body is empty or isn't valid JSON.
`invalid_upload`	400	An upload couldn't be read. Send multipart/form-data with the file in a field named file.
`unauthenticated`	401	No session cookie or bearer credential was sent.
`invalid_credentials`	401	Wrong email or password, or an API key or access token that is invalid, expired or revoked.
`mfa_required`	401	The session hasn't completed two-factor verification. Post a code to `/auth/mfa/verify`.
`forbidden`	403	Your role lacks the permission this needs; the message names it. Also returned by the administration API to anyone who isn't a platform administrator.
`organization_suspended`	403	The organization is suspended. Reads still work; changes and messaging don't.
`policy_not_accepted`	403	The organization hasn't accepted the current acceptable-use policy, which connecting accounts, launching and resuming require.
`plan_limit_reached`	403	The plan's limit on accounts, active campaigns, members or webhooks is reached, or the plan has no API access. The message says which.
`origin_rejected`	403	A cookie-authenticated change came from an origin not in `ALLOWED_ORIGINS`. Bearer requests never get this.
`not_found`	404	The resource doesn't exist, or belongs to another organization. The two cases are indistinguishable on purpose.
`route_not_found`	404	There's no such endpoint. Check the method and path.
`conflict`	409	The change conflicts with an existing record, such as a duplicate list name.
`invalid_state`	409	The object's status doesn't allow this, or changed a moment ago. Reload it and try again.
`file_too_large`	413	An upload is over its limit: 20 MB for attachments (10 MB for photos), 10 MB for imports.
`unsupported_media_type`	415	An import was neither multipart/form-data nor JSON.
`rate_limited`	429	Too many requests. Wait for the number of seconds in `Retry-After`.
`internal_error`	500	Something failed on Oqim's side. It was logged; retrying a read is safe.
`maintenance_mode`	503	The platform owner has put Oqim in maintenance. Reads still work; every change is refused until it ends. Signing in and out, two-factor verification and recipient opt-outs are never refused. Retry after the number of seconds in `Retry-After`.
`support_read_only`	403	The session is a platform administrator's support session in this organization, which is read-only: it can look, and every write is refused. Ending it, or signing out, is the only write allowed.
`support_session`	403	A support session tried to use the platform administration API. A support session belongs to the customer console and is never a way into the platform console.
`not_in_support_session`	409	Ending a support session was asked of a session that isn't one.
`queue_not_found`	404	Administration API: no queue has that name.
`queue_not_started`	409	Administration API: the queue hasn't received a task yet, so there is nothing in it to pause, resume or repair.
`task_not_found`	404	Administration API: no such task in the queue. It may have finished or been removed since the list loaded.
`task_not_retryable`	409	Administration API: only archived, retrying or scheduled tasks can be retried.
`task_active`	409	Administration API: the task is running right now and can't be dropped. Wait for it to finish, or pause the queue first.

Campaigns

Code	Status	Meaning
`campaign_invalid`	422	A pre-launch check failed. The report is in `validation`; see below.
`campaign_not_draft`	409	Only drafts can be launched or deleted.
`field_locked`	409	A field can't change in the campaign's current status; the message lists the locked fields.
`campaign_locked`	409	The campaign has finished and can't be edited.
`campaign_ended`	409	The end time has passed. Move `end_at` later before resuming.
`no_active_accounts`	409	None of the campaign's accounts can send; the message names them and why.
`paused_by_admin`	409	A platform administrator paused the campaign; the organization can't resume it.
`not_paused_by_admin`	409	Administration API: only campaigns a platform administrator paused can be resumed there.
`not_repeating`	409	Stop repeating was called on a campaign that has no repeat rule and isn't part of a series.

Telegram accounts and proxies

Code	Status	Meaning
`restriction_not_acknowledged`	409	Resuming a restricted account needs `acknowledge_restriction: true`.
`person_required`	403	A restricted account can only be resumed by a signed-in person, not an API key.
`reauth_required`	409	The account needs to sign in again; use reauth rather than resume.
`disabled_by_admin`	409	A platform administrator disabled the account.
`not_disabled_by_admin`	409	Administration API: only accounts a platform administrator disabled can be restored there.
`test_limit_reached`	429	The organization sent 20 test messages this hour, or the account 10. Launch a campaign to reach more people.
`recipient_suppressed`	422	A test message's recipient is on the suppression list.
`account_in_use`	409	The account is in a running campaign, so it can't be removed.
`proxy_in_use`	409	The proxy is already assigned to another account.
`proxy_disabled`	409	A platform administrator disabled the proxy, so it can't be checked, changed or deleted, and its address can't be added again.
`gateway_unavailable`	502	The worker that talks to Telegram can't be reached.

Recipients

Code	Status	Meaning
`recipient_exists`	409	A recipient with this Telegram ID or username already exists.
`recipient_opted_out`	409	The recipient opted out; their consent can't be changed.
`recipient_busy`	409	A message to this recipient is being sent right now. Try again in a minute.
`already_suppressed`	409	This Telegram ID or username is already on the suppression list.
`invalid_link`	404	An opt-out link is altered or incomplete.

Team, keys and webhooks

Code	Status	Meaning
`last_owner`	409	An organization needs at least one owner.
`already_member`	409	The person you invited is already a member.
`invitation_accepted`	409	The invitation was accepted, so it can't be revoked. Remove the member instead.
`invalid_invitation`	404	The invitation link isn't valid.
`invitation_usedinvitation_revokedinvitation_expired`	410	The invitation can no longer be used. Ask for a new one.
`sign_in_required`	401	The invitation is for an existing user; sign in as them to accept it.
`key_inactive`	409	A revoked or expired API key can't be rotated. Create a new one.
`webhook_disabled`	409	Enable the webhook before sending a test event.

Code	Status	Meaning
`no_organization`	403	The session has no active organization. Switch to one or create one.
`signups_closed`	403	Sign-ups are turned off on this deployment. Ask for an invitation.
`user_disabled`	403	This user was disabled by a platform administrator.
`unsupported_grant_type`	400	`POST /auth/token` accepts `grant_type` `api_key` only.
`not_applicable`	400	The endpoint is for people and an API key called it, for example the two-factor endpoints.
`mfa_enrollment_required`	403	Platform administrators must turn on two-factor authentication to use the admin console.
`mfa_setup_requiredmfa_not_enabled`	400	Call `POST /me/mfa/setup` first, or two-factor authentication isn't on.
`mfa_already_enabled`	409	Two-factor authentication is already on.

Campaign validation errors#

When a launch fails its pre-launch checks, the response carries the whole report next to the error, warnings included. The same report is saved on the campaign as validation.

422 Unprocessable Entity

{
  "error": {
    "code": "campaign_invalid",
    "message": "Fix the failed checks before launching."
  },
  "validation": {
    "ok": false,
    "checked_at": "2026-09-29T14:01:58Z",
    "estimated_hours": 6.2,
    "audience": { "matched": 1902, "sendable": 1840, "opted_out": 31, "suppressed": 6, "unknown_consent": 25, "missing_variables": 0 },
    "checks": [
      {
        "key": "accounts_authorized",
        "label": "Accounts authorized",
        "status": "FAIL",
        "message": "Expo Desk (needs to sign in again) can't send. Remove it from the campaign or fix it first."
      },
      {
        "key": "opt_out_link",
        "label": "Opt-out link",
        "status": "FAIL",
        "message": "Add {{opt_out_url}} so recipients can opt out. Platform policy requires it."
      }
    ]
  }
}

Show each check with status FAIL to whoever launched it. See pre-launch validation for every check.

Connecting an account goes through a worker that talks to Telegram. When Telegram rejects a step, the API answers with Telegram's error type as the code, in lowercase, and a readable message:

Code	Status	Meaning
`phone_code_invalid`	422	The login code is wrong. The flow allows 5 attempts.
`phone_code_expired`	410	The login code expired. Start the sign-in again.
`password_hash_invalid`	422	The two-step verification password is wrong.
`phone_number_invalid`	422	Not a phone number Telegram recognises.
`phone_number_unoccupied`	422	The number isn't registered on Telegram.
`phone_number_banned`	403	Telegram has banned this number.
`phone_number_flood`	429	Telegram paused sign-in attempts for this number. Try later.
`too_many_attempts`	429	The flow used its 5 attempts. Start again.
`flow_expiredflow_failed`	410	The sign-in attempt is over (flows last 15 minutes). Start again.
`flow_not_found`	404	No such sign-in attempt.
`proxy_unavailable`	422	The proxy chosen for the account can't be reached.
`telegram_app_invalid`	500	The deployment's TELEGRAM_APP_ID or TELEGRAM_APP_HASH is wrong. Tell the platform operator.

Errors while sending are not API errors: they land on the delivery (last_error), the send job, the account status and the message.failed webhook event. See delivery and account states.

Handling errors#

429: wait for Retry-After, then retry.
5xx and network errors: retry reads with a growing delay. Before retrying a create, check whether the first attempt succeeded.
401: the credential is missing, wrong or revoked. Retrying won't help; fix the credential.
409: the object is in the wrong state for this. Reload it; the message says what to do instead.
Other 4xx: the request needs to change. Show message, and map details onto your form fields.

Errors

Every error response has the same shape, a stable machine-readable code and a fitting HTTP status. Branch on the code; show the message to people.

Error envelope#

422 Unprocessable Entity

{
  "error": {
    "code": "validation_failed",
    "message": "Some fields need attention.",
    "details": {
      "email": "Enter a valid email address.",
      "password": "Use at least 10 characters."
    }
  }
}

code is stable; build logic on it.
message is a sentence written for people. It may change, so don't parse it.
details appears with validation_failed only, keyed by request field.
The X-Request-Id response header names the request in the API's logs. Quote it when you report a problem.

Error codes#

Code	Status	Meaning
`validation_failed`	422	One or more fields are invalid. `details` maps each field to a message.
`invalid_json`	400	The body is empty or isn't valid JSON.
`invalid_upload`	400	An upload couldn't be read. Send multipart/form-data with the file in a field named file.
`unauthenticated`	401	No session cookie or bearer credential was sent.
`invalid_credentials`	401	Wrong email or password, or an API key or access token that is invalid, expired or revoked.
`mfa_required`	401	The session hasn't completed two-factor verification. Post a code to `/auth/mfa/verify`.
`forbidden`	403	Your role lacks the permission this needs; the message names it. Also returned by the administration API to anyone who isn't a platform administrator.
`organization_suspended`	403	The organization is suspended. Reads still work; changes and messaging don't.
`policy_not_accepted`	403	The organization hasn't accepted the current acceptable-use policy, which connecting accounts, launching and resuming require.
`plan_limit_reached`	403	The plan's limit on accounts, active campaigns, members or webhooks is reached, or the plan has no API access. The message says which.
`origin_rejected`	403	A cookie-authenticated change came from an origin not in `ALLOWED_ORIGINS`. Bearer requests never get this.
`not_found`	404	The resource doesn't exist, or belongs to another organization. The two cases are indistinguishable on purpose.
`route_not_found`	404	There's no such endpoint. Check the method and path.
`conflict`	409	The change conflicts with an existing record, such as a duplicate list name.
`invalid_state`	409	The object's status doesn't allow this, or changed a moment ago. Reload it and try again.
`file_too_large`	413	An upload is over its limit: 20 MB for attachments (10 MB for photos), 10 MB for imports.
`unsupported_media_type`	415	An import was neither multipart/form-data nor JSON.
`rate_limited`	429	Too many requests. Wait for the number of seconds in `Retry-After`.
`internal_error`	500	Something failed on Oqim's side. It was logged; retrying a read is safe.
`maintenance_mode`	503	The platform owner has put Oqim in maintenance. Reads still work; every change is refused until it ends. Signing in and out, two-factor verification and recipient opt-outs are never refused. Retry after the number of seconds in `Retry-After`.
`support_read_only`	403	The session is a platform administrator's support session in this organization, which is read-only: it can look, and every write is refused. Ending it, or signing out, is the only write allowed.
`support_session`	403	A support session tried to use the platform administration API. A support session belongs to the customer console and is never a way into the platform console.
`not_in_support_session`	409	Ending a support session was asked of a session that isn't one.
`queue_not_found`	404	Administration API: no queue has that name.
`queue_not_started`	409	Administration API: the queue hasn't received a task yet, so there is nothing in it to pause, resume or repair.
`task_not_found`	404	Administration API: no such task in the queue. It may have finished or been removed since the list loaded.
`task_not_retryable`	409	Administration API: only archived, retrying or scheduled tasks can be retried.
`task_active`	409	Administration API: the task is running right now and can't be dropped. Wait for it to finish, or pause the queue first.

Campaigns

Code	Status	Meaning
`campaign_invalid`	422	A pre-launch check failed. The report is in `validation`; see below.
`campaign_not_draft`	409	Only drafts can be launched or deleted.
`field_locked`	409	A field can't change in the campaign's current status; the message lists the locked fields.
`campaign_locked`	409	The campaign has finished and can't be edited.
`campaign_ended`	409	The end time has passed. Move `end_at` later before resuming.
`no_active_accounts`	409	None of the campaign's accounts can send; the message names them and why.
`paused_by_admin`	409	A platform administrator paused the campaign; the organization can't resume it.
`not_paused_by_admin`	409	Administration API: only campaigns a platform administrator paused can be resumed there.
`not_repeating`	409	Stop repeating was called on a campaign that has no repeat rule and isn't part of a series.

Telegram accounts and proxies

Code	Status	Meaning
`restriction_not_acknowledged`	409	Resuming a restricted account needs `acknowledge_restriction: true`.
`person_required`	403	A restricted account can only be resumed by a signed-in person, not an API key.
`reauth_required`	409	The account needs to sign in again; use reauth rather than resume.
`disabled_by_admin`	409	A platform administrator disabled the account.
`not_disabled_by_admin`	409	Administration API: only accounts a platform administrator disabled can be restored there.
`test_limit_reached`	429	The organization sent 20 test messages this hour, or the account 10. Launch a campaign to reach more people.
`recipient_suppressed`	422	A test message's recipient is on the suppression list.
`account_in_use`	409	The account is in a running campaign, so it can't be removed.
`proxy_in_use`	409	The proxy is already assigned to another account.
`proxy_disabled`	409	A platform administrator disabled the proxy, so it can't be checked, changed or deleted, and its address can't be added again.
`gateway_unavailable`	502	The worker that talks to Telegram can't be reached.

Recipients

Code	Status	Meaning
`recipient_exists`	409	A recipient with this Telegram ID or username already exists.
`recipient_opted_out`	409	The recipient opted out; their consent can't be changed.
`recipient_busy`	409	A message to this recipient is being sent right now. Try again in a minute.
`already_suppressed`	409	This Telegram ID or username is already on the suppression list.
`invalid_link`	404	An opt-out link is altered or incomplete.

Team, keys and webhooks

Code	Status	Meaning
`last_owner`	409	An organization needs at least one owner.
`already_member`	409	The person you invited is already a member.
`invitation_accepted`	409	The invitation was accepted, so it can't be revoked. Remove the member instead.
`invalid_invitation`	404	The invitation link isn't valid.
`invitation_usedinvitation_revokedinvitation_expired`	410	The invitation can no longer be used. Ask for a new one.
`sign_in_required`	401	The invitation is for an existing user; sign in as them to accept it.
`key_inactive`	409	A revoked or expired API key can't be rotated. Create a new one.
`webhook_disabled`	409	Enable the webhook before sending a test event.

Code	Status	Meaning
`no_organization`	403	The session has no active organization. Switch to one or create one.
`signups_closed`	403	Sign-ups are turned off on this deployment. Ask for an invitation.
`user_disabled`	403	This user was disabled by a platform administrator.
`unsupported_grant_type`	400	`POST /auth/token` accepts `grant_type` `api_key` only.
`not_applicable`	400	The endpoint is for people and an API key called it, for example the two-factor endpoints.
`mfa_enrollment_required`	403	Platform administrators must turn on two-factor authentication to use the admin console.
`mfa_setup_requiredmfa_not_enabled`	400	Call `POST /me/mfa/setup` first, or two-factor authentication isn't on.
`mfa_already_enabled`	409	Two-factor authentication is already on.

Campaign validation errors#

When a launch fails its pre-launch checks, the response carries the whole report next to the error, warnings included. The same report is saved on the campaign as validation.

422 Unprocessable Entity

{
  "error": {
    "code": "campaign_invalid",
    "message": "Fix the failed checks before launching."
  },
  "validation": {
    "ok": false,
    "checked_at": "2026-09-29T14:01:58Z",
    "estimated_hours": 6.2,
    "audience": { "matched": 1902, "sendable": 1840, "opted_out": 31, "suppressed": 6, "unknown_consent": 25, "missing_variables": 0 },
    "checks": [
      {
        "key": "accounts_authorized",
        "label": "Accounts authorized",
        "status": "FAIL",
        "message": "Expo Desk (needs to sign in again) can't send. Remove it from the campaign or fix it first."
      },
      {
        "key": "opt_out_link",
        "label": "Opt-out link",
        "status": "FAIL",
        "message": "Add {{opt_out_url}} so recipients can opt out. Platform policy requires it."
      }
    ]
  }
}

Show each check with status FAIL to whoever launched it. See pre-launch validation for every check.

Connecting an account goes through a worker that talks to Telegram. When Telegram rejects a step, the API answers with Telegram's error type as the code, in lowercase, and a readable message:

Code	Status	Meaning
`phone_code_invalid`	422	The login code is wrong. The flow allows 5 attempts.
`phone_code_expired`	410	The login code expired. Start the sign-in again.
`password_hash_invalid`	422	The two-step verification password is wrong.
`phone_number_invalid`	422	Not a phone number Telegram recognises.
`phone_number_unoccupied`	422	The number isn't registered on Telegram.
`phone_number_banned`	403	Telegram has banned this number.
`phone_number_flood`	429	Telegram paused sign-in attempts for this number. Try later.
`too_many_attempts`	429	The flow used its 5 attempts. Start again.
`flow_expiredflow_failed`	410	The sign-in attempt is over (flows last 15 minutes). Start again.
`flow_not_found`	404	No such sign-in attempt.
`proxy_unavailable`	422	The proxy chosen for the account can't be reached.
`telegram_app_invalid`	500	The deployment's TELEGRAM_APP_ID or TELEGRAM_APP_HASH is wrong. Tell the platform operator.

Errors while sending are not API errors: they land on the delivery (last_error), the send job, the account status and the message.failed webhook event. See delivery and account states.

Handling errors#

429: wait for Retry-After, then retry.
5xx and network errors: retry reads with a growing delay. Before retrying a create, check whether the first attempt succeeded.
401: the credential is missing, wrong or revoked. Retrying won't help; fix the credential.
409: the object is in the wrong state for this. Reload it; the message says what to do instead.
Other 4xx: the request needs to change. Show message, and map details onto your form fields.

Error envelope#

Error codes#

Campaigns

Telegram accounts and proxies

Recipients

Team, keys and webhooks

Sign-in and profile

Campaign validation errors#

Telegram sign-in errors#

Handling errors#

Error envelope#

Error codes#

Campaigns

Telegram accounts and proxies

Recipients

Team, keys and webhooks

Sign-in and profile

Campaign validation errors#

Telegram sign-in errors#

Handling errors#