Erros

Toda resposta de erro da API pública segue o formato RFC 9457 (application/problem+json). O campo type de cada erro aponta para a seção do seu código nesta página (https://developers.mspdesk.com.br/erros/#<code>).

O formato do erro

Campo	O que traz
`type`	Endereço da seção do código nesta página, por exemplo `https://developers.mspdesk.com.br/erros/#not_found`.
`title`	Resumo curto do erro.
`status`	O status HTTP, repetido no corpo.
`code`	O código estável do erro, sempre em inglês (`snake_case`). É o que o seu programa deve ler.
`detail`	Explicação do que aconteceu.
`errors[]`	Nos erros de campo, uma lista de problemas com `field`, `code` e `message`.
`requestId`	Identificador da requisição.

Alguns erros trazem campos extras: layer e operation no rate_limited, e requiredScope no insufficient_scope e no scope_requires_public_api.

title, detail e errors[].message vêm no idioma do cabeçalho Accept-Language (pt-BR, en ou es; o padrão é pt-BR). Programe contra o code, nunca contra o texto: o texto pode mudar de redação e de idioma, o code não.

Ao abrir um chamado no suporte, informe o requestId da resposta.

Códigos de erro

`invalid_api_key`

Status 401. Acontece quando a chave está ausente, mal formada ou não existe. A resposta traz o cabeçalho WWW-Authenticate: Bearer. Confira se a chave foi copiada inteira e enviada como Authorization: Bearer <chave>; veja Chaves de API.

{
  "code": "invalid_api_key",
  "detail": "A chave de API apresentada é inválida, desconhecida ou está ausente.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 401,
  "title": "Chave de API inválida",
  "type": "https://developers.mspdesk.com.br/erros/#invalid_api_key"
}

`api_key_revoked`

Status 401. A chave foi revogada e não volta a funcionar. Crie uma chave nova e troque na integração.

{
  "code": "api_key_revoked",
  "detail": "Esta chave de API foi revogada e não pode mais ser usada.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 401,
  "title": "Chave de API revogada",
  "type": "https://developers.mspdesk.com.br/erros/#api_key_revoked"
}

`api_key_expired`

Status 401. A chave passou da data de expiração. Crie uma chave nova e troque na integração.

{
  "code": "api_key_expired",
  "detail": "Esta chave de API expirou e não pode mais ser usada.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 401,
  "title": "Chave de API expirada",
  "type": "https://developers.mspdesk.com.br/erros/#api_key_expired"
}

`api_key_inactive`

Status 401. A chave foi desativada. Reative-a, ou use outra chave da empresa.

{
  "code": "api_key_inactive",
  "detail": "Esta chave de API está desativada e não pode ser usada.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 401,
  "title": "Chave de API inativa",
  "type": "https://developers.mspdesk.com.br/erros/#api_key_inactive"
}

`account_inactive`

Status 403. A empresa dona da chave está inativa. Nenhuma chave dela funciona enquanto isso durar; a situação da empresa não se resolve pela integração.

{
  "code": "account_inactive",
  "detail": "A empresa associada a esta chave de API está inativa.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 403,
  "title": "Empresa inativa",
  "type": "https://developers.mspdesk.com.br/erros/#account_inactive"
}

`public_api_disabled`

Status 403. A API pública não está habilitada para a empresa e a empresa também não tem escopos liberados por concessão. As chaves existentes continuam guardadas e voltam a funcionar quando a API for habilitada. Veja Sua empresa está habilitada?.

{
  "code": "public_api_disabled",
  "detail": "A API pública não está habilitada para esta empresa. Fale com a MSP Works para habilitá-la. As chaves de API existentes continuam guardadas e voltam a funcionar quando ela for habilitada.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 403,
  "title": "API pública desabilitada",
  "type": "https://developers.mspdesk.com.br/erros/#public_api_disabled"
}

`scope_requires_public_api`

Status 403. A API pública não está habilitada e o escopo que a operação exige não está entre os liberados por concessão à empresa. Marcar o escopo na chave não resolve; o campo requiredScope diz qual escopo faltou. Veja Sua empresa está habilitada?.

{
  "code": "scope_requires_public_api",
  "detail": "A API pública não está habilitada para esta empresa, e este escopo não está entre os liberados por concessão. Marcar o escopo na chave não resolve: fale com a MSP Works para contratar a API pública.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "requiredScope": "tickets:write",
  "status": 403,
  "title": "Escopo não liberado sem a API pública",
  "type": "https://developers.mspdesk.com.br/erros/#scope_requires_public_api"
}

`insufficient_scope`

Status 403. A chave não tem o escopo que a operação exige; o campo requiredScope traz o escopo que falta, e o cabeçalho WWW-Authenticate o repete. Edite a chave e adicione o escopo (vale a partir da próxima requisição), ou crie uma chave nova com ele. Veja Escopos.

{
  "code": "insufficient_scope",
  "detail": "Esta chave de API não tem o escopo necessário para executar esta operação.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "requiredScope": "tickets:write",
  "status": 403,
  "title": "Escopo insuficiente",
  "type": "https://developers.mspdesk.com.br/erros/#insufficient_scope"
}

`forbidden`

Status 403. O acesso foi negado por uma regra de permissão que não é de escopo. Confira se o recurso pertence à empresa da chave.

`scope_not_declared`

Status 403. A rota não declara o escopo que exige, e por isso é negada por segurança. Não é um erro que a integração corrija: informe o requestId ao abrir um chamado.

`rate_limited`

Status 429. Um dos limites de uso foi atingido; o campo layer diz qual, e o cabeçalho Retry-After diz quanto esperar. Veja Limites de uso.

{
  "code": "rate_limited",
  "detail": "O limite de uso da API foi atingido. Aguarde o tempo indicado em Retry-After e tente novamente.",
  "layer": "key",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 429,
  "title": "Limite de requisições atingido",
  "type": "https://developers.mspdesk.com.br/erros/#rate_limited"
}

`malformed_body`

Status 400. O corpo da requisição não pôde ser interpretado: JSON inválido — inclusive com a mesma chave repetida no mesmo objeto — ou requisição multipart mal formada. Corrija o corpo antes de reenviar. Número com parte fracionária num campo inteiro (1.5 num id) não é arredondado: é 422 validation_failed com invalid_value no campo.

`malformed_request`

Status 400. A requisição foi recusada antes de chegar à API: a linha de requisição, o caminho ou a query têm caractere que o servidor não aceita — por exemplo <, >, espaço ou aspas sem codificar, ou barra codificada (%2F) no caminho. Codifique o valor (percent-encoding) e reenvie. Colchetes e chaves dos filtros (filter[status][eq]=) podem ir crus. A resposta traz requestId e o cabeçalho X-Request-Id, como qualquer outro erro.

{
  "code": "malformed_request",
  "detail": "A requisição foi recusada antes de ser interpretada: linha de requisição, caminho ou parâmetros de consulta com caracteres inválidos.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 400,
  "title": "Requisição malformada",
  "type": "https://developers.mspdesk.com.br/erros/#malformed_request"
}

`invalid_query`

Status 400. Um ou mais parâmetros de consulta são inválidos. A lista errors[] aponta o parâmetro em field. Veja Consultas.

{
  "code": "invalid_query",
  "detail": "Um ou mais parâmetros de consulta são inválidos.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 400,
  "title": "Parâmetros de consulta inválidos",
  "type": "https://developers.mspdesk.com.br/erros/#invalid_query"
}

`invalid_cursor`

Status 400. O cursor de paginação é inválido, ou foi gerado por outra consulta. Volte à primeira página e use apenas o cursor devolvido pela própria consulta. Veja Paginação.

{
  "code": "invalid_cursor",
  "detail": "O cursor informado é inválido ou pertence a outra consulta.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 400,
  "title": "Cursor de paginação inválido",
  "type": "https://developers.mspdesk.com.br/erros/#invalid_cursor"
}

`invalid_idempotency_key`

Status 400. O cabeçalho Idempotency-Key está em formato inválido. Veja Idempotência.

{
  "code": "invalid_idempotency_key",
  "detail": "O cabeçalho Idempotency-Key tem um formato inválido.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 400,
  "title": "Chave de idempotência inválida",
  "type": "https://developers.mspdesk.com.br/erros/#invalid_idempotency_key"
}

`not_found`

Status 404. O recurso não existe, ou não pertence à empresa da chave; uma rota inexistente também responde assim. Quando o identificador está no corpo, errors[] aponta o campo.

{
  "code": "not_found",
  "detail": "O recurso solicitado não foi encontrado.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 404,
  "title": "Recurso não encontrado",
  "type": "https://developers.mspdesk.com.br/erros/#not_found"
}

`method_not_allowed`

Status 405. O método HTTP não é aceito nesta rota. O cabeçalho Allow lista os métodos aceitos.

`not_acceptable`

Status 406. Nenhum dos formatos do cabeçalho Accept é suportado. A API responde em JSON.

`already_exists`

Status 409. Já existe um registro com os dados informados, por exemplo um valor que precisa ser único. Use o registro existente em vez de criar outro.

`resource_in_use`

Status 409. O recurso não pode ser removido porque outros registros dependem dele. Remova ou altere primeiro o que depende dele.

`concurrent_modification`

Status 409. Outra requisição alterou o recurso entre a sua leitura e a sua escrita. Releia o recurso e aplique a alteração de novo.

`idempotency_request_in_progress`

Status 409. Outra requisição com a mesma Idempotency-Key ainda está sendo executada. Espere e repita com a mesma chave. Veja Idempotência.

{
  "code": "idempotency_request_in_progress",
  "detail": "Uma requisição com a mesma chave de idempotência ainda está em execução.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 409,
  "title": "Requisição em andamento",
  "type": "https://developers.mspdesk.com.br/erros/#idempotency_request_in_progress"
}

`payload_too_large`

Status 413. O corpo da requisição passa do limite de 1 MB. Envie um corpo menor. O envio de anexo (POST /v1/tickets/{ticketId}/attachments) tem limite próprio, maior, de 6 MB por arquivo.

`unsupported_media_type`

Status 415. O Content-Type da requisição não é suportado pela rota. Envie application/json, ou o tipo que a operação indica na referência.

`validation_failed`

Status 422. Um ou mais campos do corpo são inválidos; errors[] traz um item por problema, com field, code e message. Corrija os campos apontados e reenvie.

{
  "code": "validation_failed",
  "detail": "Um ou mais campos são inválidos. Veja \"errors\" para detalhes.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 422,
  "title": "Falha de validação",
  "type": "https://developers.mspdesk.com.br/erros/#validation_failed"
}

`business_rule_violation`

Status 422. A operação viola uma regra de negócio. O detail explica qual regra; em alguns casos a resposta traz o campo violation.

`ticket_not_editable`

Status 422. O ticket está concluído ou fechado e não aceita alterações.

`ticket_deleted`

Status 422. O ticket está na lixeira e não aceita alterações.

`appointment_in_progress`

Status 422. O apontamento ainda está em andamento e não pode ser alterado. Encerre o atendimento antes de editá-lo.

`idempotency_key_reused`

Status 422. A Idempotency-Key já foi usada com um corpo diferente. Use uma chave nova para cada operação distinta. Veja Idempotência.

{
  "code": "idempotency_key_reused",
  "detail": "A chave de idempotência foi usada com um corpo de requisição diferente.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 422,
  "title": "Chave de idempotência reutilizada",
  "type": "https://developers.mspdesk.com.br/erros/#idempotency_key_reused"
}

`idempotency_unavailable`

Status 503. Não foi possível garantir a idempotência da requisição neste momento, então ela não foi executada. Repita com a mesma Idempotency-Key. Veja Idempotência.

{
  "code": "idempotency_unavailable",
  "detail": "Não foi possível garantir a idempotência da requisição neste momento. Tente novamente.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 503,
  "title": "Idempotência indisponível",
  "type": "https://developers.mspdesk.com.br/erros/#idempotency_unavailable"
}

`service_unavailable`

Status 503. O serviço, ou uma integração da qual a operação depende, está temporariamente indisponível. Repita mais tarde, com espera crescente entre as tentativas.

`internal_error`

Status 500. Falha interna do MSP Desk. Repita mais tarde; se persistir, abra um chamado e informe o requestId.