☰
Trongate Way Docs

HTTP Response Status Codes

Every API response includes an HTTP status code that tells the client, at a glance, whether the request succeeded and - if it did not - what category of error occurred. Choosing the right status code is as important as returning the right data.

Below is the complete set of status codes used in our countries API, grouped by category.

Success Codes (2xx)

Code Meaning When To Use
200 OK The request succeeded. Used for:
  • GET requests (list, detail)
  • PUT requests (update)
  • DELETE requests (with response body)
201 Created A new resource was successfully created. Used for:
  • POST requests
204 No Content The request succeeded but returns no body. Used for:
  • DELETE with no response body (alternative to 200)

Client Error Codes (4xx)

Code Meaning When To Use
400 Bad Request The request was malformed or invalid. Used for:
  • Missing required ID in URL
  • Invalid or missing JSON payload
  • Validation failure (with field-level errors)
401 Unauthorized Authentication is required and failed. Used for:
  • Missing API token
  • Invalid or expired API token
403 Forbidden The client is authenticated but lacks permission. Used for:
  • Token is valid but user level is insufficient
404 Not Found The requested resource does not exist. Used for:
  • A record ID that does not match any database row
405 Method Not Allowed The HTTP method is not supported for this endpoint. Used for:
  • A POST request sent to a read-only endpoint
429 Too Many Requests The client has exceeded a rate limit. Used when:
  • Implementing rate limiting in a before hook (see next chapter)

Server Error Codes (5xx)

Code Meaning When To Use
500 Internal Server Error An unexpected error occurred on the server. Used when:
  • A database query fails
  • An uncaught exception occurs
  • Any unforeseen server-side error

Setting Status Codes in Trongate

Trongate uses PHP's built-in http_response_code() function. Simply call it before outputting your response:

PHP
// Success
http_response_code(200);
echo json_encode($data);

// Created
http_response_code(201);
echo json_encode(['id' => $new_id]);

// Client error
http_response_code(400);
echo json_encode(['error' => 'Validation failed.', 'fields' => $errors]);

// Authentication failure
http_response_code(401);
echo json_encode(['error' => 'Unauthorized.']);

// Not found
http_response_code(404);
echo json_encode(['error' => 'Country not found.']);

Quick Reference Card

When deciding which status code to use, ask yourself these questions in order:

  1. Did the server crash? → 500
  2. Is the client authenticated? → No: 401
  3. Is the request well-formed? → No: 400
  4. Does the resource exist? → No: 404
  5. Was a resource created? → 201
  6. Everything else succeeded? → 200

This decision tree covers the vast majority of API responses. Once you internalize it, choosing the right status code becomes automatic.

We're continually improving the Trongate documentation. If anything is incorrect, unclear, incomplete, or could be better, we'd genuinely appreciate your input.

Share your thoughts in the Documentation Feedback.

Leave Feedback About This Page