Error handling

Rest API Status Codes

As a general rule, all endpoints of our API follow standard HTTP codes. Note that if you have a retry policy, it should only react to errors with 5xx codes, as 4xx errors require changes in the request to be processed correctly.

2xx Status codes

Status code	Description
200	Indicates that the request has succeeded.
201	Indicates that the request has succeeded and a new resource has been created as a result.
202	Indicates that the request has been received but not completed yet. It is typically used in log running requests and batch processing.
204	The server has fulfilled the request but does not need to return a response body. The server may return the updated meta information.

4xx Status codes

Status code	Description
400	The server could not understand the request due to incorrect syntax. The client should NOT repeat the request without modifications.
401	Indicates that the access token is expired or invalid.
403	Indicates that the request requires user authentication information. The client MAY repeat the request with a suitable Authorization header field.
404	The server can not find the requested resource.
409	The request could not be completed due to a conflict with the current state of the resource.
422	The server understands the content type and syntax of the request entity, but it is still unable to process the request for some reason. Ex. authorization credentials are invalid.

5xx Status codes

Status code	Description
500	The server encountered an unexpected condition that prevented it from fulfilling the request.
503	The server is not ready to handle the request.
504	The server is acting as a gateway and cannot get a response in time for a request.

Operation Errors

In addition to technical errors, there are a series of errors that occur during different stages of the package delivery cycle. These errors are reported both in the webhooks for package status changes and in the status endpoint.

There are three stages where these errors can occur:

Deliver parcel request
- Field failure_reason
Picking up a parcel
- Field pickup_failed.reason
Delivering a parcel
- Field delivery_attempt.fail_reason

Deliver parcel request errors

When present, it means the delivery has been rejected. These are the list of values:

payment_method_declined: There is a problem with your payment method, and the delivery has not been accepted. Check your payment methods in the business web
no_payment_methods: There is no payment method configured. Check your payment methods in the business web
requester_no_found_or_unauthorized: The requester sent in this request is not valid.
invalid_pick_up_location: There is no fleet available for your delivery area, or it's not properly configured. Please get in touch with the Logistics Team to check if we can cover your delivery area.
delivery_already_exists: This parcel has been delivered already.
unknown: Something has happened but, unfortunately, we haven't detected the reason. If the problem persists, please get in touch with the Logistics Team.

Picking up a parcel errors

The pickup process has failed because of this reason:

sender_no_show: The sender is not present.
sender_too_late: The parcel is not ready for pick up.
address_wrong: The pickup address is wrong.
address_not_found: The driver is not able to find the pickup point.
address_unsafe: The driver has refused to enter the pickup area because is not safe enough.
parcel_suspicious: The driver has refused to pick up the parcel because of the content.
parcel_packaging: The parcel is not correctly packed.
pacel_too_big_or_heavy: The parcel can't be carried in the driver's vehicle because of its weight or dimensions.
payment_requested: The driver has refused the delivery because the sender has requested some kind of payment.
payment_fake: The sender is trying to pay for the delivery using fake money.
place_closed: The pickup point is closed.
delivery_not_found: The parcel requested by the driver is not found by the sender.
already_picked_up: The parcel requested by the driver has been picked up by another driver by mistake.
delivery_cancelled: The sender has canceled the delivery.
other_with_feedback: Another different reason. You can find it in the driver_comments field.

Delivering a parcel errors

The dropoff process has failed because of this reason:

recipient_not_found: The recipient is not present at the dropoff point.
rejected: The parcel has been rejected by the recipient.
wrong_address: The dropoff address is wrong.
zone_unsafe: The driver has refused to enter the dropoff area because is not safe enough.
invalid_proof: The recipient has not provided the required code to deliver the parcel. It will be required when this proof is configured. Proofs of delivery
other: The driver has not delivered the parcel because of another different reason.