Erros e paginação

Este guia descreve como a API da Rently comunica os erros (estrutura JSON e códigos), o que significam os códigos de status HTTP mais comuns, e como percorrer respostas paginadas com os parâmetros offset e limit.

Todos os exemplos assumem que você já obteve um token Bearer. Consulte o guia de autenticação para o detalhe do fluxo. O header de autorização é enviado em cada chamada:

Authorization: Bearer {token}

Formato de erros

Quando uma requisição não pode ser concluída por um erro de negócio ou de validação, a API responde com um corpo JSON com a seguinte estrutura:

Campo	Tipo	Descrição
ErrorMessage	string (nullable)	Mensagem legível que descreve o erro.
ErrorCode	integer	Código numérico que identifica o tipo de erro (ver tabela de códigos).
Id	string (nullable)	Identificador de correlação para rastrear o erro no suporte.

observação

ErrorCode é sempre serializado como número inteiro, não como texto. Por exemplo, 1 corresponde a CustomerNotFound.

Exemplo de resposta de erro

{
  "ErrorMessage": "The requested resource was not found",
  "ErrorCode": 1,
  "Id": "0HMVB9A2K3C4D-00000001"
}

dica

Guarde o valor de Id nos seus logs. É o identificador de correlação que permite ao suporte da Rently localizar o trace exato da requisição que falhou.

Códigos de erro (ErrorCode)

O campo ErrorCode vem de uma enumeração com valores numéricos. A tabela a seguir lista todos os códigos de erro que a API pode retornar:

Code	Name	Description
0	NoError	Nenhum erro ocorreu.
1	CustomerNotFound	O cliente solicitado não foi encontrado no sistema.
2	CarNotFound	O carro solicitado não foi encontrado no sistema.
3	CarNotAvailable	O carro solicitado não está disponível para as datas especificadas.
4	PriceMismatch	O preço calculado não corresponde ao preço esperado.
5	CustomerDataNotValid	Os dados do cliente fornecidos não são válidos.
6	LanguageNotSupported	O idioma solicitado não é suportado pelo sistema.
7	InsuficientPermissions	O usuário não possui permissões suficientes para realizar a operação.
8	BookingNotFoundForCustomer	Nenhuma reserva foi encontrada para o cliente especificado.
9	BookingStatusNotAllowCancel	O status atual da reserva não permite cancelamento.
10	CreditCardNotAvailable	O cartão de crédito não está disponível para uso.
11	GatewayNotSupported	O gateway de pagamento solicitado não é suportado.
12	InfractionNotFound	A infração solicitada não foi encontrada.
13	InvlaidDates	As datas fornecidas são inválidas.
14	UnquotedReserve	A reserva não foi cotada.
15	MaxDayForQuotedReserve	O número máximo de dias para uma reserva cotada foi excedido.
21	TariffNotFound	A tarifa solicitada não foi encontrada.
22	BookingNotFound	A reserva solicitada não foi encontrada.
23	ReturnPlaceNotFound	O local de devolução especificado não foi encontrado.
24	PromotionNotFound	A promoção solicitada não foi encontrada.
25	DeliveryPlaceNotFound	O local de entrega especificado não foi encontrado.
26	BookingStatusNotAllowUpdate	O status atual da reserva não permite atualizações.
27	IlimitedKmNotEnabled	A opção de quilometragem ilimitada não está habilitada.
28	LimitedKmNotEnabled	A opção de quilometragem limitada não está habilitada.
29	MinimunDaysOfBookingNotReached	O número mínimo de dias para a reserva não foi atingido.
30	MaxDaysOfBookingReached	O número máximo de dias para a reserva foi excedido.
31	AdditionalNotFound	O item adicional solicitado não foi encontrado.
32	AdditionalMaxQuantityExceeded	A quantidade máxima para o item adicional foi excedida.
33	DateFromForBookingNotEnabled	A data de início da reserva não está habilitada.
34	DriverAgeNotAllowed	A idade do condutor não está dentro da faixa permitida.
35	BookingVersionError	Há uma divergência de versão com a reserva.
36	BookingAlreadyDelivered	A reserva já foi entregue.
37	BookingAlreadyReturned	A reserva já foi devolvida.
38	BookingNeedsToCompleteDeposit	A reserva requer um depósito para ser concluída.
39	InvalidCarKilometers	O valor de quilometragem do carro é inválido.
40	BookingStatusNotAllowDelivery	O status atual da reserva não permite a entrega.
41	DriverLicenseInvalid	A carteira de habilitação do condutor é inválida.
42	BookingStatusNotAllowReturn	O status atual da reserva não permite a devolução.
43	NotificationRelatedEntityNotFound	A entidade relacionada à notificação não foi encontrada.
44	NotificationReceiverAddressInvalid	O endereço do destinatário da notificação é inválido.
45	MailNotificationDisabled	As notificações por e-mail estão desabilitadas.
46	ReturnPlaceNotAllowedForDeliveryPlace	O local de devolução não é permitido para o local de entrega especificado.
47	BookingOutOfOfficeHoursNotAllowed	Não é permitido fazer reservas fora do horário de atendimento.
48	NotificationNotFound	A notificação solicitada não foi encontrada.
49	BlockedCustomerToBook	O cliente está bloqueado para fazer reservas.
50	MustHaveAtLeastOneInsurance	A configuração do sistema exige que pelo menos um seguro seja selecionado ao criar ou editar uma reserva.
51	InvalidCommercialAgreement	O acordo comercial é inválido.
60	AppProtocolNotFound	O protocolo de aplicação não foi encontrado.
61	ServiceTypeInvalid	O tipo de serviço é inválido.
62	ServiceStatusInvalid	O status do serviço é inválido.
63	ServiceDatesInvalids	As datas do serviço são inválidas.
64	ServiceProviderNotFound	O provedor de serviço não foi encontrado.
65	ServiceCanNotCreate	O serviço não pode ser criado.
66	ServiceCanNotEdit	O serviço não pode ser editado.
67	ServiceNotFound	O serviço solicitado não foi encontrado.
68	CarLocationInvalidDriver	A localização do carro possui um condutor inválido.
69	ReturnPlaceIsCurrentPlaceError	O local de devolução é o mesmo que o local atual.
70	CarIsNotFree	O carro não está disponível para a operação solicitada.
71	CarTransferError	Ocorreu um erro durante a transferência do carro.
72	InvalidCarGasoline	O nível de combustível do carro é inválido.
73	CannotDeliverBookingWithBalance	Não é possível entregar uma reserva com saldo pendente.
74	PlaceDoesNotAcceptCustomAddresses	O local não aceita endereços personalizados.
75	PlaceCantOperatesLikePickUp	O local não pode operar como ponto de retirada.
76	PlaceCantOperatesLikeDropOff	O local não pode operar como ponto de devolução.
77	CannotPayQuote	Não é possível pagar a cotação.
80	FeatureNotEnabled	O recurso solicitado não está habilitado.
98	ModelNotValid	O modelo não é válido.
99	Unknown	Ocorreu um erro desconhecido.
100	MissingCurrencyCode	O código da moeda está ausente.
101	TotalGreaterThanZero	O valor total deve ser maior que zero.
102	InfractionAlreadyExists	A ata de infração ou a violação já existe no sistema.
103	InvalidIncidentType	O tipo de incidente é inválido
104	InvalidIncidentDate	A data do incidente é inválida
105	SettingNotFound	Uma configuração obrigatória não foi encontrada
106	BookingBrandNotFound	Booking Brand não encontrado
107	BookingCannotBeUncancelled	—
108	RateAlreadyExists	Já existe uma taxa com o código fornecido e atualizações não foram solicitadas.
499	Timeout	—
1100	MappingAlreadyExists	—
1101	ModelNotExists	—
1102	CompanyCodeNotFound	—
1103	CommercialAgreementNotSupported	O acordo comercial não é suportado.
1104	CommercialAgreementRequired	—
1105	InfractionNoticeNotFound	O Aviso de Infração referenciado não foi encontrado para o inquilino.
1106	InfractionNoticeDismissed	O Aviso de Infração referenciado é rejeitado e não pode ser vinculado.
1107	InfractionNoticeContextMismatch	O contexto da infração (carro, data, reserva ou motorista) não corresponde ao Aviso de Infração.
1108	InfractionNoticeMainAlreadyLinked	O InfractionNotice já tem uma infração principal vinculada.
1109	InfractionNoticeNicAlreadyLinked	O InfractionNotice já tem uma infração NIC (penalidade por não identificação do motorista) vinculada.
1110	InfractionNoticeInfractionAlreadyLinked	A infração já está ligada a outro Aviso de Infração.

aviso

Os valores numéricos não são contíguos: a enumeração pula posições (por exemplo, de 15 para 21). Mapeie suas tentativas e mensagens a partir do valor exato e não assuma intervalos correlativos.

Códigos de status HTTP

A API utiliza um conjunto restrito de códigos de status. Tenha em conta que as falhas de autenticação são reportadas como 403 (a API não devolve 401).

Status	Significado	Corpo
200 OK	A requisição foi processada corretamente.	Payload do recurso ou resultado paginado.
400 Bad Request	Erro de negócio ou de validação (Api Error).	JSON com ErrorMessage, ErrorCode e Id.
403 Forbidden	Usuário não autenticado ou sem permissões para o endpoint.	Sem corpo.
404 Not Found	O recurso solicitado não existe.	Sem corpo.

observação

Um 403 pode significar tanto que o token é inválido ou ausente quanto que o usuário autenticado não tem a permissão exigida para esse endpoint. Verifique primeiro o header Authorization e depois as permissões do usuário.

Como tratar erros

• 200 → processe a resposta normalmente.
• 400 → leia ErrorCode para decidir a ação (corrigir dados, recotar, etc.) e mostre ErrorMessage ao operador.
• 403 → verifique se o token é válido, está vigente e corresponde ao mesmo tenant; confirme que o usuário tem permissões.
• 404 → o identificador usado não corresponde a nenhum recurso; valide os IDs antes de tentar de novo.

Paginação

Os endpoints que devolvem listas (por exemplo GET /api/bookings/list, GET /api/customers ou GET /api/cars) usam paginação por offset e limit.

Parâmetros de consulta

Parâmetro	Tipo	Default	Descrição
offset	integer	0	Ponto de partida da página. Deve ser >= 0.
limit	integer	30	Quantidade máxima de elementos por página. É reduzido a um máximo de 100.

observação

Se você enviar um limit maior que 100, a API o reduz automaticamente a 100. Um offset negativo é normalizado para 0.

Forma do resultado

As respostas paginadas compartilham a mesma estrutura PagedResult:

Campo	Tipo	Descrição
Offset	integer	Offset aplicado a esta página.
Limit	integer	Limite aplicado a esta página.
Total	integer	Total de elementos disponíveis em todas as páginas.
Results	array (nullable)	Elementos da página atual.
NextOffset	integer	Offset a usar para solicitar a página seguinte.

Exemplo de resposta paginada

{
  "Offset": 0,
  "Limit": 30,
  "Total": 2,
  "Results": [
    { "Id": 1 },
    { "Id": 2 }
  ],
  "NextOffset": 0
}

Exemplo de request

curl "https://{tenant}.rently.com.ar/api/customers?offset=0&limit=30&language=es-AR" \
  -H "Authorization: Bearer {token}"

Como percorrer todas as páginas

Para iterar a totalidade de uma listagem, use NextOffset de cada resposta como offset da requisição seguinte. A iteração termina quando Results traz menos elementos que Limit.

# Página 1
curl "https://{tenant}.rently.com.ar/api/bookings/list?offset=0&limit=30&language=es-AR" \
  -H "Authorization: Bearer {token}"

# Página 2: usar o NextOffset devolvido pela página anterior
curl "https://{tenant}.rently.com.ar/api/bookings/list?offset={NextOffset}&limit=30&language=es-AR" \
  -H "Authorization: Bearer {token}"

dica

Para a iteração, observe Results.Count < Limit como condição de fim em vez de comparar contra Total. Isso funciona de forma consistente com ambos os estilos de paginação da API.

aviso

Em GET /api/bookings/list o parâmetro offset funciona como cursor por Id, não como quantidade de registros a pular. Passe sempre 0 na primeira chamada (independentemente da direção de ordenação) e, nas seguintes, o valor de NextOffset que a resposta anterior devolveu. Não construa o offset manualmente somando tamanhos de página.