Errors - Lekalao

Every error of the API answers in JSON with three fields at least:

422 Unprocessable Content

{
    "message": "Not sent: ada@example.com is on the suppression list.",
    "code": "recipients_suppressed",
    "doc_url": "https://docs.lekalao.com/errors#recipients_suppressed",
    "data": { "id": "e3b0c442-98fc-4c14-9a1e-2f6b7d8a9c10", "status": "failed", "failure_code": "recipients_suppressed" }
}

Field
`message`	A sentence for a person, in the installation’s language. It may be reworded: show it, do not test it.
`code`	What went wrong, in one word that does not change. Test this one. Every code is below.
`doc_url`	This page, at the code’s entry. Under `/fr/` when the installation speaks French.

Some errors add fields of their own: errors for a validation error, problems for a campaign that is not ready, data for a transactional e-mail that was logged but not sent.

The HTTP statuses

Status	Means	What to do
`200` `201`	Done, or created.
`202`	Accepted and queued: the work happens in the background (an import, a batch of more than 100, a transactional e-mail).	Follow the `url` in the answer, the webhooks, or read the e-mail again by its `id`.
`204`	Deleted. No body.
`400`	Malformed request: an idempotency key longer than 255 characters.	Fix the call.
`401`	No token, or a revoked one.	Check the `Authorization` header.
`403`	The token, its owner’s role, the team or a test key does not allow it.	Read `code`.
`404`	Nothing of that id in this team.	Check the `id`.
`409`	Conflict: a campaign being sent, someone already in the automation, an idempotent call still running.	Read `code`; do not send it again as is.
`422`	The data, or the operation, was refused.	Read `code`, then `errors` or `message`.
`429`	Too many calls, or the month’s allowance is used up.	`rate_limited`: wait `Retry-After` seconds. `monthly_quota_exceeded`: wait for next month, or move up a plan.
`502`	A transactional e-mail the provider refused, after the retries, or the queue could not take.	Read `data.failure_reason`.
`5xx`	Lekalao’s own problem.	Try again later, with the same `Idempotency-Key`.

Validation errors

422 validation_error, with the detail field by field:

{
    "message": "The email field must be a valid email address.",
    "code": "validation_error",
    "doc_url": "https://docs.lekalao.com/errors#validation_error",
    "errors": {
        "email": ["The email field must be a valid email address."],
        "tags.2": ["The tags.2 field must not be greater than 255 characters."]
    }
}

Fields inside arrays are named by their position: subscribers.14.email is the 15th line of a batch.

An address nothing would arrive at

Adding someone new checks the address first: POST /v1/lists/{list}/subscribers, and POST /v1/automations/{automation}/trigger for a person not on the list yet. A throwaway mailbox, or a domain with no mail server, answers 422 undeliverable_address with two more fields:

{
    "message": "ada@gmial.com cannot receive e-mail: its domain has no mail server. Did you mean ada@gmail.com?",
    "code": "undeliverable_address",
    "doc_url": "https://docs.lekalao.com/errors#undeliverable_address",
    "errors": {
        "email": ["ada@gmial.com cannot receive e-mail: its domain has no mail server. Did you mean ada@gmail.com?"]
    },
    "problem": "no_mail_server",
    "suggestion": "ada@gmail.com"
}

Field	Value
`problem`	`disposable`: a throwaway mailbox. `no_mail_server`: the domain receives no e-mail.
`suggestion`	The address the person very likely meant, when a common domain is one or two keystrokes away. Otherwise `null`.

Show suggestion to the person and let them choose: never swap it in on your own. In a batch, the same address is a line with "outcome": "failed" and its message; in an import, a line in error.

Retry or not

Retry on 429 rate_limited, on 5xx and on network errors, with a growing delay and the same Idempotency-Key.
Read first a 502 from a transactional e-mail: data.failure_reason says whether sending again can work.
Do not retry any other 4xx: the same call gives the same answer. Fix it first. One exception: 409 idempotency_key_in_use, the same idempotent call still running; try again a moment later.

Every code

Grouped by where they come from. Each one has its anchor: /errors#rate_limited.

Any route

`unauthenticated`

401. No Authorization header, a malformed token, or a revoked one. Check that the whole token follows Bearer . See Authentication.

`missing_ability`

403. A Read token called a route that writes. Create a Read and write token for this application.

`role_not_allowed`

403. The token’s owner may not do this in the team: a viewer writing, a writer sending a campaign. A token acts with its owner’s role, checked on every call. See The roles.

`team_suspended`

403. The team is suspended: every call is refused until whoever runs the service lifts it. Contact support.

`team_access_lost`

403. The token’s owner is no longer a member of the team the token was made in. Create a token from an account that is.

`two_factor_required`

403. The team requires two-factor authentication, and the token’s owner has neither a second factor nor a passkey. Once they set one up, the token works again. See Rules of the team.

`no_team`

403. The account is in no team at all. It happens to someone removed from every team.

`forbidden`

403. Refused for a reason that has no code of its own. message says which.

`not_found`

404. No route at this address, or no resource of this id in the token’s team. A resource of another team is not found either, by design.

`method_not_allowed`

405. The route exists, with another method: GET instead of POST, say.

`conflict`

409. The state of the resource does not allow it. message says why.

`bad_request`

400. The request could not be read.

`payload_too_large`

413. The body is larger than the server accepts. Send fewer lines per batch, or a smaller file.

`validation_error`

422. A field is missing or invalid. errors lists them, field by field. See Validation errors.

`invalid_request`

422. Refused for a reason that has no code of its own. message says which.

`rate_limited`

429. The token made more than its calls of the minute (120 by default). Wait the Retry-After seconds; X-RateLimit-Remaining says, on every answer, how many calls are left.

`server_error`

500. Lekalao’s fault. Try again later with the same Idempotency-Key; if it lasts, tell support the time of the call.

`service_unavailable`

503. The installation is in maintenance. Try again in a few minutes.

Idempotency

`idempotency_key_too_long`

400. The Idempotency-Key is longer than 255 characters.

`idempotency_key_in_use`

409. A call with the same key is still running. Try again a moment later: you will get its answer.

`idempotency_key_reused`

422. The key was already used for another route or another body. Give each operation its own key.

`idempotency_key_expired`

422. The key is more than 24 hours old. Send a new one. See Idempotency.

Test keys

`sandbox_cannot_send`

403. A test key called a route that exists to write to real people: sending a campaign, putting someone into an automation, sending a confirmation e-mail again. Use a live key.

Contacts

`undeliverable_address`

422. The address cannot receive e-mail: a throwaway mailbox, or a domain without a mail server. See An address nothing would arrive at.

`address_suppressed`

422. The address is on the team’s suppression list: it bounced for good, complained, or was blocked by hand. It cannot be subscribed again by the API.

`subscriber_limit_reached`

422. The plan holds no more subscribers. Move up a plan, or clean the lists. See Plans.

`confirmation_not_needed`

422. resend-confirmation for someone who has nothing to confirm: already subscribed, or on a list without double opt-in.

`batch_rejected`

422. Not one line of the batch could be saved. data gives the reason of each line, meta the counts.

`contact_not_found`

404. A conversion for an address that is on none of the team’s lists.

`event_count_out_of_range`

422. POST /v1/events takes one event, or between 1 and 1,000 under events.

Sending

`sender_not_allowed`

422. The sender address is not on a verified sending domain of the team, where the installation requires one. The message names the domain. See Sending domains.

`template_error`

422. The template does not render: a tag left open, an unknown filter. The message says where.

`content_missing`

422. A transactional e-mail with neither template nor html.

`recipient_missing`

422. A transactional e-mail with no to, from a template that has no default recipients either.

`too_many_recipients`

422. More than 50 addresses in one transactional e-mail, to, cc and bcc together. A transactional e-mail is written to someone: send one each.

`recipients_suppressed`

422. Every address in to is on the suppression list. The e-mail is logged as failed, under data. Sending it again fails the same way.

`monthly_quota_exceeded`

429. The plan’s e-mails of the month are used up; each recipient of an e-mail counts, copies included. The e-mail is logged as failed, under data. Wait for the next month, or move up a plan. A campaign test refused for this reason answers test_refused.

`sending_paused`

422. The team may not send: its paid period ended without a payment. The e-mail is logged as failed, under data. See Billing.

`provider_error`

502. The provider refused the transactional e-mail on every try, for six hours, or a test key wrote to failed@sink.lekalao.dev. data.failure_reason holds the provider’s last word.

`queue_unavailable`

502. The e-mail was logged, but the queue could not take it. Try again in a moment with the same Idempotency-Key: a 502 is not kept, so the e-mail is not counted twice.

`mail_not_kept`

409. A resend of a transactional e-mail whose template keeps neither the content nor the variables (one-time codes, sign-in links). Send a new e-mail.

`campaign_not_ready`

422. The campaign cannot leave yet. problems lists what is missing, as the interface does. See Ready or not.

`campaign_is_sending`

409. A campaign being sent cannot be deleted. Pause it in the interface first.

`test_refused`

422. A campaign test that may not leave: the sender’s domain is not verified (where the installation requires it), every address given is on the suppression list, the team has sent 100 test e-mails this hour, or the month’s allowance is used up. message says which.

`automation_not_running`

409. The automation is not active, or has no list. Switch it on in the interface.

`already_in_automation`

409. The person is already travelling through this automation. The answer also carries "started": false.

Licences

`licence_invalid`

422. POST /v1/licences/check: the key cannot be read, or is not signed by Lekalao. The answer also carries "valid": false, "reason": "invalid".

`licence_revoked`

403. The licence has been revoked. The answer also carries "valid": false, "reason": "revoked".

A transactional e-mail that failed

A transactional e-mail keeps why it failed in failure_code, with the same words as the codes above: recipients_suppressed, monthly_quota_exceeded, sending_paused, provider_error, queue_unavailable. One more is never an answer to a call, since it happens later: lost, an e-mail still pending seven hours after the call because its job was lost. Send it again. See Transactional e-mails.

​The HTTP statuses

​Validation errors

​An address nothing would arrive at

​Retry or not

​Every code

​Any route

​unauthenticated

​missing_ability

​role_not_allowed

​team_suspended

​team_access_lost

​two_factor_required

​no_team

​forbidden

​not_found

​method_not_allowed

​conflict

​bad_request

​payload_too_large

​validation_error

​invalid_request

​rate_limited

​server_error

​service_unavailable

​Idempotency

​idempotency_key_too_long

​idempotency_key_in_use

​idempotency_key_reused

​idempotency_key_expired

​Test keys

​sandbox_cannot_send

​Contacts

​undeliverable_address

​address_suppressed

​subscriber_limit_reached

​confirmation_not_needed

​batch_rejected

​contact_not_found

​event_count_out_of_range

​Sending

​sender_not_allowed

​template_error

​content_missing

​recipient_missing

​too_many_recipients

​recipients_suppressed

​monthly_quota_exceeded

​sending_paused

​provider_error

​queue_unavailable

​mail_not_kept

​campaign_not_ready

​campaign_is_sending

​test_refused

​automation_not_running

​already_in_automation

​Licences

​licence_invalid

​licence_revoked

​A transactional e-mail that failed