Errors

Every error uses the same envelope. The HTTP status tells you the category; errorCode tells you exactly what happened and whether retrying is worth it.

json

{
  "success": false,
  "message": "This store's fleet cannot currently accept orders.",
  "data": {
    "errorCode": "FLEET_SUSPENDED",
    "retryable": false,
    "action": "A new fleet must be selected for the store."
  }
}

message is written to be shown to a human. errorCode is what your code should branch on — messages may be reworded, codes will not.

Catalogue

Request shape

Code	errorCode	Cause	Retry
`400`	`MALFORMED_REQUEST`	The body could not be parsed: invalid JSON, empty body, or a field of the wrong type	No — fix the body

data.fields names the offending fields:

json

{
  "success": false,
  "message": "fleetId alanı beklenen türde değil.",
  "data": {
    "errorCode": "MALFORMED_REQUEST",
    "retryable": false,
    "fields": ["fleetId"]
  }
}

The difference from 422: a 422 means we read the body and its contents broke a rule. A 400 means we never got to read it.

Authentication

Status	Code	Cause	Retry
`401`	`TOKEN_EXPIRED`	Token aged out	Yes — renew, resend once
`401`	`INVALID_CREDENTIALS`	Wrong, revoked or suspended credentials	No

Store

Status	Code	Cause	Retry
`409`	`STORE_NOT_CONFIGURED`	No fleet attached, or store not active	No
`409`	`ALREADY_HIZLIYO_PARTNER`	This branch is already a direct Hızlıyo partner	No
`409`	`STORE_EXISTS_ON_ANOTHER_VENDOR`	This branch is registered by another integrator	No
`409`	`DUPLICATE_STORE`	You already registered this branch under a different store id — reuse it	No
`422`	`INVALID_TAX_NUMBER`	Tax number missing or malformed	No

Order

Status	Code	Cause	Retry
`423`	`FLEET_SUSPENDED`	The fleet cannot accept orders (commercial reason)	No — the store needs a different fleet
`423`	`FLEET_TERMINATED`	The fleet's channel is closed	No
`503`	`FLEET_UNAVAILABLE`	No available courier in the area right now	Yes — after ~60 s
`422`	`DROPOFF_OUT_OF_COVERAGE`	Address outside the fleet's coverage	No
`422`	`COORDINATE_MISMATCH`	Coordinates disagree with the address text by more than 2 km	No — fix the data
`422`	`INVALID_RECIPIENT`	Recipient name too short or missing	No
`422`	`INVALID_PHONE`	Phone is not a valid 10-digit number	No
`422`	`INVALID_ADDRESS`	Address text too short	No
`422`	`READY_AT_TOO_FAR`	`readyAt` more than 4 hours in the future	No
`409`	`DUPLICATE_ORDER`	Same `externalOrderId` with different content	No
`409`	`CANCEL_TOO_LATE`	Courier already picked the package up	No
`404`	`ORDER_NOT_FOUND`	Unknown `orderId`, or it belongs to another account	No

Throttling

Status	Code	Cause	Retry
`429`	`RATE_LIMITED`	Rate limit exceeded	Yes — after `Retry-After` seconds

Retrying, honestly

Only three codes are worth retrying: TOKEN_EXPIRED, FLEET_UNAVAILABLE and RATE_LIMITED. Everything else is a decision or a data problem, and repeating the request will produce the same answer while burning your rate limit.

Remember that we never retry on your behalf — see Orders › Retry policy.

Showing errors to restaurants

The restaurant is your user, not ours. A few suggestions from what actually helps:

Code	Unhelpful	Helpful
`FLEET_UNAVAILABLE`	"Delivery error"	"No courier available right now. Trying again."
`FLEET_SUSPENDED`	"423 error"	"Your courier company is not accepting orders. Please contact them."
`COORDINATE_MISMATCH`	"Invalid request"	"The address and map location do not match. Please check the pin."
`STORE_NOT_CONFIGURED`	"Store error"	"No courier company is set up for this branch yet."

Something unexpected

5xx responses other than 503 FLEET_UNAVAILABLE mean something broke on our side. They are logged with a correlation id; if you contact us, include the orderId or the X-Idempotency-Key you sent and the approximate time.

Errors ​

Catalogue ​

Request shape ​

Authentication ​

Store ​

Order ​

Throttling ​

Retrying, honestly ​

Showing errors to restaurants ​

Something unexpected ​