Errors
Overview
When requesting tokens, errors may occur due to various client-side issues. The token endpoint utilizes standard HTTP response codes to communicate the outcome of requests
The following code ranges are applicable:
2xx: Request was successful.
4xx: Request failed due to a client error.
5xx: Request failed due to a temporary server error. Retry the request after a brief delay.
Authentication
| Error code | Wolt Response | Most frequent reason | Solution |
|---|---|---|---|
| 405 | 1. Wrong HTTP method (HTTP 405 - Method Not Allowed) | Using GET, PUT, DELETE instead of POST method | Use POST call method |
| 401 | 2. Invalid client credentials (HTTP 401 - Unauthorized) { "error": "invalid_client", "error_description": "Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method)." } | Client ID or client secret is incorrect Client does not exist in the system | Check if credentials are included in the request |
| 400 | 3. Malformed authorization header (HTTP 400 - Bad Request) { "error": "invalid_request", "error_description": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Client credentials missing or malformed in both HTTP Authorization header and HTTP POST body." } | Using Bearer instead of Basic authentication scheme Missing Basic prefix in Base64-encoded credentials Authorization header is completely missing | Check the type of authentication used in the request Check encoding logic in the request To create {{base64_encoded_client_credentials}}, encode your client_id:client_secret to Base64 using: echo -n "your_client_id:your_client_secret" | base64 However, the -u flag automatically creates the correct Authorization: Basic base64(client_id:client_secret) header and is the recommended approach. |
| 400 | 4. Missing grant_type parameter (HTTP 400 - Bad Request) | The grant_type parameter is missing from the request | Add grant_type to the request.If auth_code request:-d "grant_type=authorization_code If refresh_token request:-d "grant_type=refresh_token |
| 400 | 5. Invalid grant parameters (HTTP 400 - Bad Request) | ||
| 5.1 Authorization code already used { "error": "invalid_grant", "error_description": "The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. The authorization code has already been used." } | Attempting to use the same authorization code twice (codes are single-use only) | Don’t try to use auth_code more than once. First time: Use authorization code to get access token + refresh token After that: Use refresh token to get new access token + new refresh token | |
| 400 | 5.2 Authorization code issues{ "error": "invalid_grant", "error_description": "The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client." } | Authorization code has expired (valid for 1 hour only) Authorization code is malformed or doesn't exist Authorization code parameter is missing from the request | |
| 400 | 5.3 Authorization code client mismatch { "error": "invalid_grant", "error_description": "The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. The OAuth 2.0 Client ID from this request does not match the one from the authorize request." } | Authorization code was obtained for Client A but used with Client B's credentialsDifferent client credentials are used than the ones that obtained the code Authorization code obtained using client_a_id:client_a_secret Token request made using client_b_id:client_b_secret with that same code Result: This specific error even though both clients are valid | Make sure that authorization code has been received with the right set of client_id and client_secret. |
| 400 | 5.4 Wrong redirect URI { "error": "invalid_grant", "error_description": "The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. The 'redirect_uri' from this request does not match the one from the authorize request." } | The redirect_uri parameter doesn't exactly match the one used during authorization | |
| 400 | 5.5 Refresh token issues {"error": "invalid_grant", "error_description": "The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. The refresh token is malformed or not valid."} {"error": "invalid_grant", "error_description": "The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. The refresh token expired."} | Refresh token is invalid or malformed Refresh token has expired (after 30 days) | |
| 400 | 5.6 Wrong parameter combinations { "error": "invalid_grant", "error_description": "The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."} | Mixing parameters from different grant types |
Order & Venue endpoints
| Error code | Wolt Response | Most frequent reason | Solution |
| 400 | HTTP 400 – Bad Request | Malformed JSON, invalid properties, missing required fields, or invalid datetime format (must be ISO8601 with UTC Z). | Validate the request body against the API spec. For datetime fields use format YYYY-MM-DDThh:mm:ssZ. |
| 401 | HTTP 401 – Unauthorized | Not authorized to perform requested operation | Use the correct, up-to-date credentials. |
| 404 | HTTP 404 – Not Found | The requested resource cannot be found. This can occur if:the endpoint path does not existorder_id is not foundthe venue_id is invalid | Verify that you are calling a valid endpoint. Check that both venue_id and order_id are correct and active before retrying. |
| 405 | HTTP 405 – Method Not Allowed | Wrong HTTP method used for the endpoint. | Use the method defined in the API reference (e.g., POST for accept/reject; PATCH for status updates). |
| 409 | HTTP 409 – Conflict | Invalid state transition (e.g., trying to mark an order “Ready” before it was “Accepted”; attempting to accept/reject an order that is already in a terminal state). Pre-order confirmation outside the allowed window. Operation not allowed in current state (e.g., “NotReady”). | Only perform valid state transitions (Accept → Ready → Delivered). Confirm pre-orders within the allowed time window. Always check current order status before sending state-changing requests. |
| 422 | HTTP 422 – Unprocessable Entity | The request is syntactically correct but fails business validation. Examples:- Refund item id does not exist in the order | Ensure refunded items exist in the order |
| 429 | HTTP 429 – Too Many Requests | Rate limit exceeded for Order operations. | Implement exponential backoff and respect documented rate limits. |
| 500 | HTTP 500 – Internal Server Error | Unexpected server-side error while processing the request. | Retry after a brief delay; if persistent, contact Wolt support |
| 503 | HTTP 503 – Service Unavailable | Service temporarily unavailable (maintenance or transient outage). | Retry after a brief delay; if persistent, contact Wolt support |
Menu endpoints
| Error code | Wolt Response | Most frequent reason | Solution |
| 400 | HTTP 400 - Bad Request | POST /menu: content sent is not supported and failed validation. Check the detailed error message body for more specific information, supplied when a “known” error is existing within your request body. | This is usually indicative of an error in the structure of your menu file:a required value missingan unsupported parameter type sentany issue in content validation |
| PATCH /inventory | This is usually indicative of an error in the structure of your request body, such as an unsupported format, or properties that are not supported; Check the endpoint API reference and adjust accordingly. | ||
| PATCH /items | This is usually indicative of an error in the structure of your request body, such as an unsupported format, or properties that are not supported; Check the endpoint API reference and adjust accordingly. | ||
| PATCH /options/values | This is usually indicative of an error in the structure of your request body, such as an unsupported format, or properties that are not supported; Check the endpoint API reference and adjust accordingly. | ||
| 401 | HTTP 401 - Unauthorized | All endpoints:Wrong credentials usedVenue is not enabled to use Menu endpoints | Use the correct, up-to-date credentials. |
| 403 | HTTP 403 - Forbidden | ||
| 405 | HTTP 405 - Method Not Allowed | All endpoints: Wrong method used | Use only the method described in the documentation. |
| 406 | HTTP 406 - Not acceptable | POST Menu: body of the request is sent as an unsupported format. | Check the endpoint API reference and adjust accordingly. |
| 500 | All endpoints: Temporary issue to process on the Wolt servers. | Try again later; exhaust the process after 5 retry cycles. |