API v1 · Guia

Erros

Formato do erro, status HTTP e a tabela de códigos que a API do Rumo CRM devolve.

Todo endpoint erra do mesmo jeito: status HTTP honesto e o mesmo corpo. Trate pelo code, que é estável. A message é para gente ler e pode mudar de texto. Um ?limt=10 com erro de digitação, por exemplo, responde 400:

JSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "unknown_parameter",
    "message": "Parâmetro desconhecido: limt.",
    "param": "limt",
    "requestId": "req_7f3c2a9be1d04c6f8a5e2b7c9d1e0f34"
  }
}

Todo erro responde { "error": { "type", "code", "message", "param", "requestId" } }. type é a família do erro e code o motivo exato, estável para o seu código tratar. message é texto para gente ler e pode mudar. param aparece quando o erro é de um parâmetro específico.

Status	`type`	`code`	Quando
400	`invalid_request_error`	`invalid_parameter`	Parâmetro com valor inválido (veja `param`).
400	`invalid_request_error`	`unknown_parameter`	Parâmetro que a operação não aceita (erro de digitação, por exemplo).
400	`invalid_request_error`	`invalid_cursor`	`cursor` alterado ou de outra lista.
400	`invalid_request_error`	`invalid_json`	Corpo do pedido que não é um JSON válido.
400	`invalid_request_error`	`company_not_found`	`companyId` que não é uma empresa ativa da sua conta.
400	`invalid_request_error`	`owner_not_found`	`ownerId` que não é um usuário ativo da sua empresa.
400	`invalid_request_error`	`contact_not_found`	`contactId` que não é um contato que você vê.
400	`invalid_request_error`	`pipeline_not_found`	`pipelineId` que não é um funil da sua conta.
400	`invalid_request_error`	`pipeline_inactive`	Funil desativado: negócio novo não nasce nele.
400	`invalid_request_error`	`stage_not_found`	`stageId` que não é uma etapa da sua conta.
400	`invalid_request_error`	`stage_not_in_pipeline`	A etapa enviada não pertence ao funil enviado.
400	`invalid_request_error`	`stage_is_final`	Etapa de ganho ou perda onde a operação não aceita etapa final (para fechar, use `/win` ou `/lose`).
400	`invalid_request_error`	`stage_change_not_allowed`	Etapa ou resultado do negócio enviados no PATCH. Use `/move`, `/win` ou `/lose`.
400	`invalid_request_error`	`lost_reason_not_found`	`lostReasonId` que não é um motivo de perda da conta válido para o funil do negócio.
400	`invalid_request_error`	`product_not_found`	`productId` que não é um produto do catálogo da conta.
400	`invalid_request_error`	`unknown_custom_field`	Campo personalizado (`slug`) que não existe (veja `param`).
400	`invalid_request_error`	`invalid_custom_field_value`	Valor fora do tipo do campo personalizado (veja `param`).
400	`invalid_request_error`	`invalid_idempotency_key`	`Idempotency-Key` vazia, com mais de 255 caracteres ou fora do ASCII visível.
401	`authentication_error`	`missing_api_token`	Pedido sem o cabeçalho `Authorization`.
401	`authentication_error`	`invalid_bearer_token`	Cabeçalho `Authorization` fora do formato `Bearer <token>`.
401	`authentication_error`	`invalid_api_token`	Token inexistente, expirado, revogado ou de usuário sem acesso à empresa.
402	`permission_error`	`subscription_inactive`	A assinatura da empresa não está ativa.
403	`permission_error`	`insufficient_api_token_scope`	O token não tem o escopo exigido pela operação.
403	`permission_error`	`permission_denied`	O seu papel não permite a operação.
404	`not_found_error`	`resource_not_found`	O registro não existe, é de outra empresa ou está fora do seu papel.
409	`conflict_error`	`idempotency_key_reused`	`Idempotency-Key` já usada com outro pedido.
409	`conflict_error`	`idempotency_key_in_progress`	Pedido com a mesma `Idempotency-Key` ainda em andamento.
409	`conflict_error`	`phone_already_in_use`	O telefone já pertence a outro contato da empresa.
409	`conflict_error`	`cnpj_already_in_use`	Outra empresa da conta já usa este CNPJ.
409	`conflict_error`	`channel_disconnected`	Envio por um canal desligado ou que precisa ser reconectado.
422	`invalid_request_error`	`missing_required_custom_fields`	Falta valor em campo personalizado obrigatório (veja `param` e `message`).
422	`invalid_request_error`	`pipeline_without_won_stage`	O funil do negócio não tem etapa de ganho.
422	`invalid_request_error`	`pipeline_without_lost_stage`	O funil do negócio não tem etapa de perda.
422	`invalid_request_error`	(vários)	O pedido é válido, mas a mensagem não pode ser enviada nesta conversa agora: janela de 24 horas, template, descadastro, grupo. Veja a tabela de "Enviar mensagem na conversa".
429	`rate_limit_error`	`rate_limited`	Limite de pedidos por minuto atingido. Espere `Retry-After` segundos.
500	`api_error`	`internal_error`	Falha nossa. Tente de novo e, se continuar, informe o `Request-Id`.
503	`api_error`	`api_tokens_disabled`	Acesso por token suspenso temporariamente.
503	`api_error`	`queue_unavailable`	A fila de envio de mensagens está fora do ar. Nada foi enviado; tente de novo.
503	`api_error`	`template_check_unavailable`	Não deu para consultar os templates do WhatsApp agora. Nada foi enviado; tente de novo.
503	`api_error`	`idempotency_unavailable`	Não foi possível garantir a idempotência numa operação que exige isso (envio de mensagem). Nada foi executado; tente de novo.

Toda resposta, de sucesso ou de erro, traz o cabeçalho Request-Id. Informe esse valor ao suporte para localizarmos o pedido.

Quando repetir o pedido

Resposta	Repetir?
`429 rate_limited`	Sim, depois de `Retry-After` segundos.
`409 idempotency_key_in_progress`	Sim, quando o primeiro pedido terminar, com a mesma `Idempotency-Key`.
`500`, `503` e queda de conexão	Sim, com espera crescente (1 s, 2 s, 4 s…) e, em escrita, a mesma `Idempotency-Key`.
Outros `4xx`	Não. O mesmo pedido terá a mesma resposta: corrija o que o `code` e o `param` apontam.

PróximoIdempotência