Error handling

GipoNext APIs use standard HTTP status codes to communicate the outcome of each request. This page describes the most common codes, the error body format, and strategies for handling each situation in your code.

HTTP status codes

Success responses

Code	Meaning	When you receive it
200 OK	Request completed successfully	Read, update
201 Created	Resource created successfully	Creation of a new resource
204 No Content	Operation completed, no body	Delete, operations without response

Client errors

Code	Meaning	What to do
400 Bad Request	Malformed request or invalid parameters	Check the response body for details. Verify required fields, types, and formats.
401 Unauthorized	Token missing, expired, or invalid	Renew the access token with the refresh token. If the refresh token has also expired, start a new login. See OAuth flows and tokens.
403 Forbidden	Valid token but insufficient permissions	The user lacks permission for this operation, or the required OAuth scope is missing. Verify scope and user role.
404 Not Found	Resource not found	The specified ID does not exist or is not accessible for the current tenant. Verify tenantId and resource ID.
409 Conflict	Conflict with current resource state	Another operation modified the resource in the meantime. Re-read the resource and retry.
422 Unprocessable Entity	Syntactically valid but semantically invalid data	The body is valid JSON but values fail business rules. Check the error detail in the response.
429 Too Many Requests	Traffic limit exceeded	Wait for the time indicated in the Retry-After header and retry. See Rate limiting.

Server errors

Code	Meaning	What to do
500 Internal Server Error	Unexpected server error	Not caused by your code. Retry after a few seconds. If it persists, contact support.
502 Bad Gateway / 503 Service Unavailable	Service temporarily unavailable	Retry with exponential backoff. The service should return shortly.

Error body format

When a request fails, the response body is JSON and contains useful information about the cause.

{
  "message": "Human-readable error description",
  "errors": {
    "FieldName": [
      "Specific detail about the validation failure"
    ]
  }
}

💡 Note

Not all errors include the errors field. Present fields depend on the error type. The message field is always present in error responses with a body.

Error handling strategy

Recoverable (retry automatically)

• 401: renew the token and retry the original request.
• 429: wait Retry-After seconds and retry.
• 5xx: retry with exponential backoff (e.g. 1s, 2s, 4s) up to 3 attempts.

Non-recoverable (fix the request)

• 400: parameters are wrong. Read the body to see which field failed validation.
• 403: user lacks permissions. Verify OAuth scope and user role in the tenant.
• 404: resource does not exist. Verify tenantId and resource ID.
• 422: data violates business rules. Read the body and correct the values.

Troubleshooting checklist

When a call fails, follow this sequence:

1. Check the HTTP code — first useful clue for the problem category.
2. Read the response body — the message field and, if present, errors tell you what went wrong.
3. Verify the token — if you get 401, the token may be expired. If you get 403, a scope may be missing.
4. Verify tenantId — if you get 404 for a resource you know exists, you may be using the wrong tenantId.
5. Check rate limits — if you get 429, you are sending too many requests. See Rate limiting.
6. Retry (if appropriate) — for 401 (after refresh), 429 (after wait), and 5xx (after backoff).
7. Contact support — if the problem persists after checks, write to support with endpoint, HTTP code, error body, and timestamp.

Next steps

• Rate limiting — handling 429 specifically
• OAuth flows and tokens — token renewal and expiration handling
• Entities and operations — scopes required for each resource