Erros

Os erros seguem a RFC 9457 (application/problem+json). O campo type é uma URL estável que identifica o erro: trate os erros pelo type, nunca pelo texto de title.

Campos

Campo	Descrição
`type`	URL do tipo de erro: `https://developers.tfshop.cloud/errors/<tipo>`.
`title`	Resumo legível, em inglês.
`status`	O status HTTP.
`detail`	Explicação deste caso.
`instance`	Id da requisição (`req_…`), o mesmo do cabeçalho `X-Request-Id`.
`errors`	Em `validation_failed`: lista de `{ field, message }`.

http

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
X-Request-Id: req_7Kd2mQ9xT4bV1n

{
  "type": "https://developers.tfshop.cloud/errors/insufficient_scope",
  "title": "The token lacks the scope this operation requires",
  "status": 403,
  "detail": "This operation requires the invoices:write scope.",
  "instance": "req_7Kd2mQ9xT4bV1n"
}

http

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://developers.tfshop.cloud/errors/validation_failed",
  "title": "The request has invalid fields",
  "status": 422,
  "instance": "req_3Hn8pW2sK6cY0r",
  "errors": [
    { "field": "access_key", "message": "Invalid check digit." }
  ]
}

Toda resposta traz X-Request-Id. Informe-o ao suporte; o lojista vê o mesmo id no registro de chamadas do painel.

Tipos de erro

type	Status	Quando acontece	O que fazer
unauthorized	401	Token ausente, inválido ou revogado.	Confira o cabeçalho `Authorization`. Se o token foi revogado, peça outro ao lojista ou refaça o OAuth.
insufficient_scope	403	O token não tem o escopo exigido pelo endpoint.	Veja o escopo na referência. Token da loja: crie outro com o escopo. App: peça o escopo à TF e o lojista reinstala.
app_suspended	403	O app foi suspenso pela TF.	Pare as chamadas e fale com a TF. As instalações foram revogadas.
sandbox_read_only	403	Um token `tfs_test_` tentou alterar o catálogo.	Use um token `tfs_live_` para escrever produtos, preços e estoque.
not_found	404	O recurso não existe nesta loja.	Confira o id. Recursos de outras lojas nunca são visíveis.
method_not_allowed	405	O método HTTP não existe neste caminho.	Veja os métodos aceitos na referência.
invalid_state	409	A ação não vale no estado atual do pedido (por exemplo, enviar um pedido cancelado).	Busque o pedido com GET e decida a partir do estado atual.
invoice_issuer_mismatch	409	A loja emite NF-e pelo TF Fiscal, não pelo ERP.	Não emita a nota no ERP. Se o lojista quiser emitir pelo ERP, ele troca o emissor no painel.
test_order	409	NF-e enviada para um pedido de teste com token de produção.	Pule os pedidos com `test: true`.
fiscal_document_required	409	Envio informado sem NF-e autorizada nem DC-e.	Envie a NF-e primeiro, ou o lojista gera a DC-e na loja.
validation_failed	422	Corpo ou parâmetros inválidos.	Corrija os campos listados em `errors`.
idempotency_key_reuse	422	A mesma `Idempotency-Key` foi usada com outra requisição.	Gere uma chave nova para cada operação diferente.
rate_limited	429	O limite de requisições foi excedido.	Espere os segundos de `Retry-After` e reduza o ritmo.
internal_error	500	Erro inesperado do nosso lado (`500`), ou serviço indisponível (`503`).	É temporário: tente de novo com espera exponencial e jitter. Em `POST`, reenvie com a mesma `Idempotency-Key`. Se persistir, informe o `X-Request-Id` ao suporte.

Campos

Campo	Descrição
`type`	URL do tipo de erro: `https://developers.tfshop.cloud/errors/<tipo>`.
`title`	Resumo legível, em inglês.
`status`	O status HTTP.
`detail`	Explicação deste caso.
`instance`	Id da requisição (`req_…`), o mesmo do cabeçalho `X-Request-Id`.
`errors`	Em `validation_failed`: lista de `{ field, message }`.

http

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
X-Request-Id: req_7Kd2mQ9xT4bV1n

{
  "type": "https://developers.tfshop.cloud/errors/insufficient_scope",
  "title": "The token lacks the scope this operation requires",
  "status": 403,
  "detail": "This operation requires the invoices:write scope.",
  "instance": "req_7Kd2mQ9xT4bV1n"
}

http

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://developers.tfshop.cloud/errors/validation_failed",
  "title": "The request has invalid fields",
  "status": 422,
  "instance": "req_3Hn8pW2sK6cY0r",
  "errors": [
    { "field": "access_key", "message": "Invalid check digit." }
  ]
}

Toda resposta traz X-Request-Id. Informe-o ao suporte; o lojista vê o mesmo id no registro de chamadas do painel.

Tipos de erro

type	Status	Quando acontece	O que fazer
unauthorized	401	Token ausente, inválido ou revogado.	Confira o cabeçalho `Authorization`. Se o token foi revogado, peça outro ao lojista ou refaça o OAuth.
insufficient_scope	403	O token não tem o escopo exigido pelo endpoint.	Veja o escopo na referência. Token da loja: crie outro com o escopo. App: peça o escopo à TF e o lojista reinstala.
app_suspended	403	O app foi suspenso pela TF.	Pare as chamadas e fale com a TF. As instalações foram revogadas.
sandbox_read_only	403	Um token `tfs_test_` tentou alterar o catálogo.	Use um token `tfs_live_` para escrever produtos, preços e estoque.
not_found	404	O recurso não existe nesta loja.	Confira o id. Recursos de outras lojas nunca são visíveis.
method_not_allowed	405	O método HTTP não existe neste caminho.	Veja os métodos aceitos na referência.
invalid_state	409	A ação não vale no estado atual do pedido (por exemplo, enviar um pedido cancelado).	Busque o pedido com GET e decida a partir do estado atual.
invoice_issuer_mismatch	409	A loja emite NF-e pelo TF Fiscal, não pelo ERP.	Não emita a nota no ERP. Se o lojista quiser emitir pelo ERP, ele troca o emissor no painel.
test_order	409	NF-e enviada para um pedido de teste com token de produção.	Pule os pedidos com `test: true`.
fiscal_document_required	409	Envio informado sem NF-e autorizada nem DC-e.	Envie a NF-e primeiro, ou o lojista gera a DC-e na loja.
validation_failed	422	Corpo ou parâmetros inválidos.	Corrija os campos listados em `errors`.
idempotency_key_reuse	422	A mesma `Idempotency-Key` foi usada com outra requisição.	Gere uma chave nova para cada operação diferente.
rate_limited	429	O limite de requisições foi excedido.	Espere os segundos de `Retry-After` e reduza o ritmo.
internal_error	500	Erro inesperado do nosso lado (`500`), ou serviço indisponível (`503`).	É temporário: tente de novo com espera exponencial e jitter. Em `POST`, reenvie com a mesma `Idempotency-Key`. Se persistir, informe o `X-Request-Id` ao suporte.