Pular para o conteúdo principal

Status de Erros

A API do TapSign utiliza codigos de status HTTP padrao combinados com codigos de erro internos para indicar o resultado de cada requisicao. Este guia detalha todos os cenarios de erro e como trata-los.

Codigos de Status HTTP​

CodigoStatusDescricao
200OKRequisicao processada com sucesso
201CreatedRecurso criado com sucesso
204No ContentRequisicao processada, sem conteudo na resposta (ex: DELETE)
400Bad RequestRequisicao invalida -- parametros ausentes ou incorretos
401UnauthorizedNao autenticado -- token ausente, invalido ou expirado
402Payment RequiredPagamento necessario -- limite do plano atingido
403ForbiddenNao autorizado -- sem permissao para acessar este recurso
404Not FoundRecurso nao encontrado
409ConflictConflito -- o recurso ja existe ou esta em estado incompativel
422Unprocessable EntityEntidade nao processavel -- dados validos sintaticamente mas invalidos semanticamente
429Too Many RequestsRate limit excedido -- consulte Politicas de Rate Limit
500Internal Server ErrorErro interno do servidor -- tente novamente ou contate o suporte

Formato padrao de erro​

Todas as respostas de erro seguem um formato JSON consistente:

{
  "error": {
    "code": "CODIGO_DO_ERRO",
    "message": "Descricao legivel do erro.",
    "details": {}
  }
}
CampoTipoDescricao
codestringCodigo de erro interno para tratamento programatico
messagestringMensagem legivel descrevendo o erro
detailsobject ou array ou nullInformacoes adicionais sobre o erro (pode ser nulo)
Dica

Sempre utilize o campo code para tratamento programatico de erros, nao o campo message. As mensagens podem mudar sem aviso, mas os codigos sao estaveis.

Codigos de erro internos​

Erros de validacao​

CodigoHTTPDescricao
VALIDATION_ERROR400Um ou mais campos da requisicao sao invalidos
INVALID_PARAMETER400Parametro com formato ou valor invalido
MISSING_REQUIRED_FIELD400Campo obrigatorio ausente na requisicao
INVALID_FILE_FORMAT400Formato de arquivo nao suportado
FILE_TOO_LARGE400Arquivo excede o tamanho maximo permitido

Erros de autenticacao e autorizacao​

CodigoHTTPDescricao
AUTHENTICATION_ERROR401Token ausente ou invalido
TOKEN_EXPIRED401Token JWT expirado -- utilize o refresh token
INVALID_API_KEY401API Key invalida ou revogada
FORBIDDEN403Sem permissao para acessar este recurso
ORGANIZATION_SUSPENDED403Organizacao suspensa -- entre em contato com o suporte

Erros de plano e limites​

CodigoHTTPDescricao
PLAN_LIMIT_EXCEEDED402Limite de documentos do plano atingido
FEATURE_NOT_AVAILABLE402Funcionalidade nao disponivel no seu plano
RATE_LIMIT_EXCEEDED429Limite de requisicoes por minuto excedido

Erros de recurso​

CodigoHTTPDescricao
RESOURCE_NOT_FOUND404O recurso solicitado nao foi encontrado
ENVELOPE_NOT_FOUND404Envelope nao encontrado
DOCUMENT_NOT_FOUND404Documento nao encontrado
SIGNER_NOT_FOUND404Signatario nao encontrado
TEMPLATE_NOT_FOUND404Modelo nao encontrado
WEBHOOK_NOT_FOUND404Webhook nao encontrado

Erros de conflito e estado​

CodigoHTTPDescricao
RESOURCE_ALREADY_EXISTS409O recurso ja existe (ex: webhook duplicado)
ENVELOPE_ALREADY_SENT409Envelope ja foi enviado para assinatura
ENVELOPE_ALREADY_CANCELED409Envelope ja foi cancelado
ENVELOPE_ALREADY_COMPLETED409Envelope ja foi completado (todos assinaram)
INVALID_ENVELOPE_STATE422Acao invalida para o estado atual do envelope
SIGNER_ALREADY_SIGNED409Signatario ja assinou este envelope

Erros internos​

CodigoHTTPDescricao
INTERNAL_ERROR500Erro interno inesperado
SERVICE_UNAVAILABLE503Servico temporariamente indisponivel

Exemplos de respostas de erro​

400 - Erro de validacao​

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A requisicao contem campos invalidos.",
    "details": [
      {
        "field": "signers[0].email",
        "message": "Email invalido"
      },
      {
        "field": "signers[0].name",
        "message": "O campo 'name' e obrigatorio"
      }
    ]
  }
}

401 - Token expirado​

{
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "O token de acesso expirou. Utilize o refresh token para obter um novo.",
    "details": {
      "expired_at": "2026-03-29T14:30:00Z"
    }
  }
}

402 - Limite do plano​

{
  "error": {
    "code": "PLAN_LIMIT_EXCEEDED",
    "message": "Voce atingiu o limite de documentos do seu plano.",
    "details": {
      "plan": "Profissional",
      "limit": 100,
      "used": 100,
      "upgrade_url": "https://app.tapsign.com.br/settings/billing"
    }
  }
}

403 - Sem permissao​

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Voce nao tem permissao para acessar este recurso.",
    "details": {
      "required_permission": "envelopes:write",
      "your_permissions": ["envelopes:read", "documents:read"]
    }
  }
}

404 - Recurso nao encontrado​

{
  "error": {
    "code": "ENVELOPE_NOT_FOUND",
    "message": "Envelope nao encontrado.",
    "details": {
      "envelope_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }
}

409 - Conflito de estado​

{
  "error": {
    "code": "ENVELOPE_ALREADY_SENT",
    "message": "Este envelope ja foi enviado para assinatura e nao pode ser modificado.",
    "details": {
      "envelope_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "sent_at": "2026-03-29T10:00:00Z",
      "status": "sent"
    }
  }
}

422 - Estado invalido​

{
  "error": {
    "code": "INVALID_ENVELOPE_STATE",
    "message": "Nao e possivel enviar um envelope sem signatarios.",
    "details": {
      "envelope_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "current_status": "draft",
      "required": "Adicione pelo menos um signatario antes de enviar"
    }
  }
}

429 - Rate limit​

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de requisicoes excedido. Tente novamente em 32 segundos.",
    "details": {
      "limit": 300,
      "remaining": 0,
      "reset_at": "2026-03-29T14:01:00Z",
      "retry_after": 32
    }
  }
}

500 - Erro interno​

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Ocorreu um erro interno. Tente novamente em alguns instantes.",
    "details": {
      "request_id": "req_abc123def456"
    }
  }
}
Erros 500

Se voce receber um erro 500, inclua o request_id ao entrar em contato com o suporte pelo email suporte@tapsign.com.br. Isso nos ajuda a investigar o problema rapidamente.

Tratamento de erros​

Exemplo em JavaScript​

async function createEnvelope(data) {
  const response = await fetch('https://api.tapsign.com.br/v1/envelopes', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer tsk_live_abc123def456',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    const body = await response.json();
    const error = body.error;

    switch (error.code) {
      case 'VALIDATION_ERROR':
        // Tratar campos invalidos
        console.error('Campos invalidos:', error.details);
        break;

      case 'TOKEN_EXPIRED':
        // Renovar token e tentar novamente
        await refreshToken();
        return createEnvelope(data);

      case 'PLAN_LIMIT_EXCEEDED':
        // Notificar usuario sobre limite do plano
        console.error('Limite do plano atingido');
        break;

      case 'RATE_LIMIT_EXCEEDED':
        // Aguardar e tentar novamente
        const retryAfter = error.details.retry_after;
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        return createEnvelope(data);

      default:
        console.error(`Erro ${error.code}: ${error.message}`);
    }

    throw new Error(error.message);
  }

  return response.json();
}

Exemplo em Python​

import requests
import time

def create_envelope(data):
    response = requests.post(
        "https://api.tapsign.com.br/v1/envelopes",
        headers={
            "Authorization": "Bearer tsk_live_abc123def456",
            "Content-Type": "application/json"
        },
        json=data
    )

    if not response.ok:
        error = response.json()["error"]

        if error["code"] == "VALIDATION_ERROR":
            print(f"Campos invalidos: {error['details']}")

        elif error["code"] == "TOKEN_EXPIRED":
            refresh_token()
            return create_envelope(data)

        elif error["code"] == "PLAN_LIMIT_EXCEEDED":
            print("Limite do plano atingido")

        elif error["code"] == "RATE_LIMIT_EXCEEDED":
            retry_after = error["details"]["retry_after"]
            time.sleep(retry_after)
            return create_envelope(data)

        raise Exception(f"{error['code']}: {error['message']}")

    return response.json()
Boas praticas
  1. Sempre verifique o campo code para tratamento programatico -- nao dependa da mensagem
  2. Implemente retry para erros 429 e 500 -- use backoff exponencial
  3. Logue o request_id de erros 500 para facilitar o suporte
  4. Trate erros 401 renovando o token automaticamente quando possivel
  5. Valide dados localmente antes de enviar para a API para reduzir erros 400

Proxima secao: Documentos -- Crie documentos via API.