Search in documentation

Modules

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Solutions

Errors and troubleshooting

HTTP error codes returned by the Catalog API, diagnosis of common issues, and best practices for resilient integrations.

HTTP error codes

`400 Bad Request`

The request is malformed. Check:

Required fields are filled.
Correct format of values (dates in ISO 8601, prices as numbers).
Referenced IDs exist in the system.
Request body is valid JSON.

`401 Unauthorized`

The token expired or is invalid. Get a new accessToken and try again. See Authentication.

`403 Forbidden`

You do not have permission for the operation. Common causes:

Resource exclusive to another vertical (e.g., wholesale pricing in restaurant account).
Module not contracted for your account.
Attempt to access data from another account.

`404 Not Found`

The resource does not exist. Confirm that merchantId, catalogId, itemId, and other IDs are correct and that the resource was actually created.

`409 Conflict`

Duplicate resource or incompatible change. Examples:

externalCode already in use by another item.
Attempt to change an item's type to a value incompatible with the category.

`413 Payload Too Large`

The request exceeded the size limit. Occurs in:

Image upload above 5 MB.
Batch with many items.

Split into smaller requests.

`422 Unprocessable Entity`

The data violates business rules. Check:

Item has price defined.
min of an add-on group is less than or equal to max.
The store has at most one PIZZA category.
Pizza categories have all mandatory groups (SIZE, CRUST, EDGE, TOPPING).

`429 Too Many Requests`

You exceeded the rate limit. Wait before retrying. Implement exponential backoff (see best practices).

`500 Internal Server Error`

Error on iFood's server. Try again in a few minutes. If it persists, open a ticket with the batchId or call timestamp.

Diagnosis of common issues

Item does not appear in the app

Check in this order:

Item has status: AVAILABLE
Category has status: AVAILABLE
Item has price.value defined
Each mandatory add-on group has at least one option with status AVAILABLE
Availability by shift covers the current time
Sales context is correct

Check the response from the item listing or catalog endpoint to confirm that the item was created and its attributes are correct.

Price or status changes do not appear

Batch endpoints run asynchronously. After calling the endpoint:

Save the returned batchId
Check GET /batch/{batchId} every 5–10 seconds
Wait for status: COMPLETED
Check result: SUCCESS for each item in results

If an item failed, confirm that productId or externalCode exists and that you have permission in that context.

Error creating pizza

Pizzas require this structure:

Item with type: "PIZZA"
Omit categoryId (the API creates the category automatically)
Include the groups SIZE, CRUST, EDGE, and TOPPING
Each group needs at least one option with price defined

Example of a size option:

{
  "id": "size-id",
  "status": "AVAILABLE",
  "productId": "size-product-id",
  "fractions": [1, 2],
  "externalCode": "size_code"
}

See the complete guide at Pizza.

Duplicate `externalCode`

The API reuses products with the same externalCode. If you don't want reuse, use unique codes. If reuse is intentional (e.g., sharing a product between two items), keep the same externalCode.

`contextModifiers` has no effect

Confirm:

catalogContext is a valid value (DEFAULT, WHITELABEL, INDOOR).
contextModifiers is an array inside the entity (item or option).
The context exists in the store's catalog.
Values in contextModifiers override root values only in the specified context.

Image does not appear

Confirm:

Format jpg, jpeg, or png.
Size less than 5 MB.
imagePath was filled with the upload endpoint's return.
The upload returned 200 OK.

Best practices

Validate before going to production

Before activating the integration:

Use the provided test merchant.
Test each flow (create, update, pause, delete).
Validate with GET /catalogs/{catalogId}/categories?include_items=true to confirm that items and add-ons were created correctly.

Use `externalCode` for traceability

Include a unique externalCode in each item and add-on. You can:

Update resources using your own ID
Track changes originating in your system
Do bidirectional synchronization without depending on iFood IDs

Implement retry with exponential backoff

For operations subject to transient failures (5xx, 429, timeouts):

Attempt	Wait
1	Immediate
2	1 s
3	2 s
4	4 s

Do not retry on 4xx (except 429) — the problem is in the payload, not the server.

Monitor batch operations

Do not assume a batch finished by immediate return:

Save the batchId
Check GET /batch/{batchId} until status: COMPLETED
Record individual failures in results

{
  "batchId": "batch-123",
  "status": "COMPLETED",
  "results": [
    { "resourceId": "item-1", "result": "SUCCESS" },
    { "resourceId": "item-2", "result": "FAILURE" }
  ]
}

Use `contextModifiers` instead of duplicating items

Create the item once and adjust price, status, and code per context. Duplicating items per channel makes maintenance difficult and causes divergences.

Log calls and responses

Store for each operation:

Timestamp
Endpoint and method
Payload sent
Response received (including batchId)

These logs are essential for debugging and opening support tickets.

Support

If the problem persists, open a ticket at Developer Portal Support with:

Affected merchantId.
Endpoint and method called.
IDs of involved resources.
Complete error response.
Call timestamp.

Was this page helpful?

Rate your experience in the new Developer portal:

Errors and troubleshooting

HTTP error codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

413 Payload Too Large

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error