Erros - Sailer

Toda resposta que não é 2xx tem o mesmo body:

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "email is not a valid address.",
    "param": "email",
    "detail": [
      { "field": "email", "message": "value is not a valid email address", "code": "value_error" }
    ],
    "request_id": "b7c1d2e3-f4a5-4b6c-8d7e-9f0a1b2c3d4e",
    "documentation_url": "https://docs.chatsailer.com/guides/errors#validation_failed"
  }
}

Desvie por type para o fluxo de controle e por code para o tratamento específico. Os dois são estáveis; message é escrito para humanos e pode ser reescrito. Sempre logue request_id. Ele é ecoado no header de resposta X-Request-ID, e citá-lo nos deixa encontrar a sua requisição exata.

Tipos

Type	HTTP	O que significa	O que fazer
`invalid_request_error`	400, 422	A requisição está malformada ou falha a validação	Corrija a requisição. Leia `detail` para os campos ofensores. Não tente de novo sem mudanças
`authentication_error`	401	Token ausente, malformado, revogado ou expirado	Cheque o header `Authorization`. Não tente de novo sem mudanças
`permission_error`	403	Autenticado, mas não permitido	Costuma ser um scope faltando, ou uma política de write do workspace. Veja abaixo
`not_found_error`	404	Não existe esse registro, ou ele está fora do seu workspace	Não tente de novo
`conflict_error`	409	Conflita com o estado existente, p. ex. um duplicado	Reconcilie, depois tente de novo
`rate_limit_error`	429	Pedidos demais	Faça backoff e tente de novo — veja abaixo
`api_error`	5xx	Algo quebrou do nosso lado	Tente de novo com backoff. Se persistir, mande o `request_id`

Um 404 não distingue “não existe” de “pertence a outro workspace”. É deliberado: distinguir os dois deixaria qualquer um sondar ids de registro entre workspaces.

Scopes faltando

Um 403 de um cheque de scope nomeia exatamente o que falta, para você não ter que adivinhar:

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This connection is missing the required scope(s): contacts:write. Call GET /v1/me to see what it has.",
    "param": "contacts:write"
  }
}

Um 403 que não é insufficient_scope costuma significar política de write do workspace — por exemplo, uma entidade espelhada de um CRM externo. Chame GET /v1/capabilities para ver quais entidades você pode escrever.

Tentando de novo

Tente de novo rate_limit_error e api_error. Não tente de novo erros 4xx sem mudanças; eles vão falhar igual.

for attempt in range(5):
    response = httpx.request(method, url, headers=headers, json=body)
    if response.status_code < 400:
        return response.json()
    if response.status_code not in (429, 500, 502, 503, 504):
        raise SailerError(response.json()["error"])
    time.sleep(2 ** attempt)

Use backoff exponencial com jitter. Tentar de novo imediatamente durante um rate limit o estende.

Códigos de erro

Todos os error.code, agrupados por status HTTP. error.documentation_url leva direto à entrada do código que você recebeu. Os códigos são permanentes: use-os para decidir o que fazer.

HTTP 400

bad_request

Não foi possível entender a requisição.

invalid_cursor

O cursor está corrompido ou foi emitido para outra consulta. Envie links.next sem alterações, com os mesmos filtros e a mesma ordenação.

unknown_expand

Um relacionamento em expand não existe neste recurso.

expand_limit_exceeded

Relacionamentos demais em expand; o limite é 4.

unknown_field

Um nome em fields não existe neste recurso.

unknown_sort_field

Este recurso não pode ser ordenado por essa chave.

unknown_entity

Nenhum recurso tem esse nome.

too_many_filter_values

Um parâmetro de filtro foi repetido mais vezes do que o permitido.

unsupported_sort

Esta coleção não pode ser ordenada assim.

invalid_window

A janela de tempo está vazia ou invertida.

HTTP 401

unauthorized

O token está ausente, é desconhecido, foi revogado ou expirou.

token_expired

O token de acesso OAuth expirou. Renove-o e tente de novo.

HTTP 403

insufficient_scope

Falta ao token um escopo de que este endpoint precisa; param nomeia o primeiro que falta. GET /v1/me lista o que o token tem.

forbidden

A requisição não é permitida para este token.

local_write_denied

O workspace desligou este tipo de escrita, em geral porque um CRM externo é a fonte da verdade. GET /v1/capabilities mostra a política.

user_grant_denied

A pessoa que autorizou esta conexão OAuth não pode fazer essa alteração na Sailer.

note_author_only

Só a pessoa da equipe que escreveu a nota pode alterá-la ou excluí-la.

conversation_access_denied

A pessoa que autorizou esta conexão OAuth não pode agir nesta conversa na Sailer.

channel_access_denied

A pessoa que autorizou esta conexão OAuth não pode usar um canal pelo qual esta campanha envia.

campaign_dispatch_denied

A pessoa que autorizou esta conexão OAuth não tem permissão para enviar campanhas.

HTTP 404

not_found

Não existe esse registro neste workspace.

contact_not_found

Um id de contato na requisição não existe neste workspace.

pipeline_not_found

O id do funil não existe neste workspace.

stage_not_found

Não há etapa com esse id ou nome no funil.

record_not_found

Um id de contato, organização ou negócio no corpo não existe neste workspace ou não é visível para este token; param nomeia o campo, como record_id, contact_id ou organization_id.

HTTP 405

api_error

O método não é suportado neste caminho.

HTTP 409

conflict

A requisição conflita com o estado atual.

already_exists

O registro já existe.

external_id_taken

Outro registro do mesmo recurso já tem esse external_id; a mensagem diz qual.

external_id_conflict

O external_id e o phone de um upsert apontam para contatos diferentes, ou o contato encontrado já tem outro external id.

phone_mismatch

O contato com esse external_id tem outro telefone. O upsert nunca muda o telefone de um contato.

contact_already_exists

Já existe um contato com esse telefone; a mensagem diz qual. POST /v1/contacts/upsert cria ou atualiza numa chamada só.

campaign_not_accepting_participants

A campanha terminou e não aceita novos participantes.

idempotency_key_reused

Esse Idempotency-Key já foi usado com outro corpo. Use uma chave nova para uma requisição nova.

idempotency_key_in_flight

Uma requisição com esse Idempotency-Key ainda está em processamento. Tente de novo quando ela terminar.

tag_already_exists

O catálogo de tags do recurso já tem uma tag com esse nome.

conversation_closed

A conversa está encerrada; não pode ser transferida, atribuída nem retomada.

conversation_not_with_ai

Uma pessoa da equipe ou a fila já está com esta conversa, então não há o que transferir. Use assign para trocar a pessoa.

conversation_with_ai

O agente de IA está com esta conversa. Use handoff para passá-la a uma pessoa antes.

conversation_already_with_ai

O agente de IA já está com esta conversa.

conversation_has_no_contact

A conversa não tem contato, ou o contato não existe mais, então não pode ser encerrada por aqui.

no_agent_available

A fila da conversa não tem um agente de IA ativo com parte do trabalho para recebê-la de volta.

conversation_queue_unavailable

A fila em que a conversa está não existe mais, então ela não pode ser transferida. Mova-a para outra fila na Sailer.

campaign_not_running

Só uma campanha em execução pode ser pausada.

campaign_not_paused

Só uma campanha pausada pode ser retomada.

campaign_not_ready

Falta à campanha uma configuração de que ela precisa para enviar; a mensagem diz qual.

campaign_has_no_message

A campanha não tem mensagem ativa para enviar.

campaign_template_variables_unresolved

Uma variável de template na mensagem da campanha não pode ser preenchida.

campaign_template_not_approved

Um template que a campanha envia ainda não foi aprovado pelo WhatsApp.

campaign_channel_unavailable

Um canal pelo qual a campanha envia está faltando ou inativo.

already_reversed

Este evento já foi estornado; um evento só pode ser estornado uma vez.

not_a_record

Um estorno não pode ser estornado.

HTTP 422

validation_failed

Alguns campos são inválidos; detail lista cada um. Problemas de query, caminho ou header respondem 400 com o mesmo código.

invalid_request

A requisição está bem formada, mas não pode ser aplicada como foi enviada.

stage_not_in_pipeline

A etapa pertence a um funil diferente do do negócio.

agent_activity_read_only

Esta atividade é o plano do agente de IA de falar de novo com o contato; ela só pode ser concluída ou cancelada.

assignee_not_found

O assignee_id não é de uma pessoa da equipe que possa assumir esta conversa.

won_reason_without_won

won_reason só é aceito com outcome: won.

unknown_event_code

O workspace não tem tipo de evento de sucesso com esse código. GET /v1/success-event-types lista os tipos.

value_basis_mismatch

O tipo de evento exige um value e nenhum foi enviado, ou proíbe e um foi enviado.

HTTP 429

rate_limit_exceeded

Requisições demais neste token. Espere Retry-After segundos antes de tentar de novo.

HTTP 500

internal_error

Algo deu errado do nosso lado. Tente de novo com backoff e informe error.request_id ao suporte se persistir.

Códigos por campo

Um erro validation_failed lista cada campo problemático em detail, com um destes códigos ou um tipo de validação padrão como missing.

Código	Significado
`unknown_field_path`	O filtro nomeia um campo que não pode ser filtrado.
`filter_too_deep`	Os grupos do filtro aninham mais de 4 níveis.
`too_many_conditions`	O filtro tem mais de 50 condições.
`reserved_field_key`	Uma chave de campo personalizado colide com um campo padrão; defina-o no nível de cima.
`unknown_custom_field`	Não há campo personalizado com essa chave no recurso. `GET /v1/fields` lista os campos.
`required_field_missing`	O workspace exige este campo na criação.
`ambiguous_stage`	Mais de uma etapa do funil tem esse nome.
`deal_needs_a_party`	Um negócio precisa de `contact_id`, `organization_id` ou ambos.
`unknown_entity`	Nenhum recurso tem esse nome.
`unknown_tag`	Não há tag com esse id no workspace.
`tag_resource_mismatch`	A tag pertence ao catálogo de outro recurso.
`unknown_lost_reason`	Não há motivo de perda com esse id no workspace.
`deal_not_lost`	Um motivo de perda só vale para um negócio perdido.
`lost_reason_required`	Criar ou marcar um negócio como perdido exige um `lost_reason_id` na mesma requisição.
`status_required`	`status` não pode ser apagado.
`content_required`	O conteúdo de uma nota não pode ser apagado.
`field_required`	Este campo não pode ser apagado.
`unknown_user`	Não há usuário com esse id no workspace.

​Tipos

​Scopes faltando

​Tentando de novo

​Códigos de erro

​HTTP 400

​bad_request

​invalid_cursor

​unknown_expand

​expand_limit_exceeded

​unknown_field

​unknown_sort_field

​unknown_entity

​too_many_filter_values

​unsupported_sort

​invalid_window

​HTTP 401

​unauthorized

​token_expired

​HTTP 403

​insufficient_scope

​forbidden

​local_write_denied

​user_grant_denied

​note_author_only

​conversation_access_denied

​channel_access_denied

​campaign_dispatch_denied

​HTTP 404

​not_found

​contact_not_found

​pipeline_not_found

​stage_not_found

​record_not_found

​HTTP 405

​api_error

​HTTP 409

​conflict

​already_exists

​external_id_taken

​external_id_conflict

​phone_mismatch

​contact_already_exists

​campaign_not_accepting_participants

​idempotency_key_reused

​idempotency_key_in_flight

​tag_already_exists

​conversation_closed

​conversation_not_with_ai

​conversation_with_ai

​conversation_already_with_ai

​conversation_has_no_contact

​no_agent_available

​conversation_queue_unavailable

​campaign_not_running

​campaign_not_paused

​campaign_not_ready

​campaign_has_no_message

​campaign_template_variables_unresolved

​campaign_template_not_approved

​campaign_channel_unavailable

​already_reversed

​not_a_record

​HTTP 422

​validation_failed

​invalid_request

​stage_not_in_pipeline

​agent_activity_read_only

​assignee_not_found

​won_reason_without_won

​unknown_event_code

​value_basis_mismatch

​HTTP 429

​rate_limit_exceeded

​HTTP 500

​internal_error

​Códigos por campo

Tipos

Scopes faltando

Tentando de novo

Códigos de erro

HTTP 400

bad_request

invalid_cursor

unknown_expand

expand_limit_exceeded

unknown_field

unknown_sort_field

unknown_entity

too_many_filter_values

unsupported_sort

invalid_window

HTTP 401

unauthorized

token_expired

HTTP 403

insufficient_scope

forbidden

local_write_denied

user_grant_denied

note_author_only

conversation_access_denied

channel_access_denied

campaign_dispatch_denied

HTTP 404

not_found

contact_not_found

pipeline_not_found

stage_not_found

record_not_found

HTTP 405

api_error

HTTP 409

conflict

already_exists

external_id_taken

external_id_conflict

phone_mismatch

contact_already_exists

campaign_not_accepting_participants

idempotency_key_reused

idempotency_key_in_flight

tag_already_exists

conversation_closed

conversation_not_with_ai

conversation_with_ai

conversation_already_with_ai

conversation_has_no_contact

no_agent_available

conversation_queue_unavailable

campaign_not_running

campaign_not_paused

campaign_not_ready

campaign_has_no_message

campaign_template_variables_unresolved

campaign_template_not_approved

campaign_channel_unavailable

already_reversed

not_a_record

HTTP 422

validation_failed

invalid_request

stage_not_in_pipeline

agent_activity_read_only

assignee_not_found

won_reason_without_won

unknown_event_code

value_basis_mismatch

HTTP 429

rate_limit_exceeded

HTTP 500

internal_error

Códigos por campo