Error Handling

Learn how to handle API errors gracefully in your integration.

Error Response Format

When an error occurs, the API returns a JSON response with success: false and details about the error:

error-response.json

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password must be at least 8 characters."]
  }
}

HTTP Status Codes

The API uses standard HTTP status codes to indicate success or failure:

200OK

Request succeeded

201Created

Resource created successfully

204No Content

Request succeeded, no content to return (e.g., DELETE)

400Bad Request

Invalid request body or parameters

401Unauthorized

Missing or invalid authentication token

403Forbidden

Authenticated but lacking required permissions

404Not Found

Requested resource does not exist

422Unprocessable Entity

Validation failed for the request data

429Too Many Requests

Rate limit exceeded

500Internal Server Error

Server encountered an unexpected error

Validation Errors

Validation errors (400/422) include an errors object with field-specific error messages:

validation-error.json

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email field is required.",
      "The email must be a valid email address."
    ],
    "date_of_birth": [
      "The date of birth must be a date before today."
    ],
    "phone": [
      "The phone format is invalid."
    ]
  }
}

Each field may have multiple error messages. Display all messages to help users correct their input.

Error Handling Examples

Here's how to implement comprehensive error handling in your application:

interface ApiError {
  success: false;
  message: string;
  errors?: Record<string, string[]>;
}

async function createPerson(data: PersonData) {
  try {
    const response = await fetch('https://api.mployr.com.au/v1/people', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${token}`,
      },
      body: JSON.stringify(data),
    });

    if (!response.ok) {
      const error: ApiError = await response.json();

      switch (response.status) {
        case 400:
          // Validation errors
          console.error('Validation failed:', error.errors);
          break;
        case 401:
          // Unauthorized - token expired or invalid
          await refreshToken();
          return createPerson(data); // Retry
        case 403:
          // Forbidden - insufficient permissions
          throw new Error('You do not have permission for this action');
        case 404:
          // Not found
          throw new Error('Resource not found');
        case 429:
          // Rate limited
          const retryAfter = response.headers.get('Retry-After') || '60';
          await sleep(parseInt(retryAfter) * 1000);
          return createPerson(data); // Retry
        case 500:
          // Server error
          throw new Error('Server error. Please try again later.');
        default:
          throw new Error(error.message);
      }
    }

    return response.json();
  } catch (error) {
    console.error('Request failed:', error);
    throw error;
  }
}

Common Error Scenarios

401 Token Expired

Access tokens expire after 24 hours. Implement token refresh or re-authentication logic.

{
  "success": false,
  "message": "Unauthenticated."
}

403 Permission Denied

The user is authenticated but lacks permission for the requested action.

{
  "success": false,
  "message": "This action is unauthorized."
}

404 Resource Not Found

The requested resource doesn't exist or has been deleted.

{
  "success": false,
  "message": "No query results for model [App\\Models\\People] with ID 999."
}

Best Practices

Always Check success Field

Don't rely solely on HTTP status codes. Always check the success field in the response body.

Display User-Friendly Messages

Map API error messages to user-friendly text. Some error messages are technical and should be translated for end users.

Log Errors for Debugging

Log full error responses server-side for debugging, but only show relevant information to users.

Implement Retry Logic

For transient errors (429, 500, 503), implement retry logic with exponential backoff.

Next Steps

Learn about webhooks for real-time event notifications.